Work in Progress — Bundles are an active development area. This guide describes intended user value and observed automation behavior from the codebase, but it is not a GA feature contract. Confirm details (SLA, UI parity, supported Git hosts) with your Loopback operator.

Bundles — from Git to running software

Bundles are Loopback’s path for taking your application source code in Git and turning it into built artifacts and deployments on a Kubernetes workspace. They sit alongside — not inside — the Kubernetes applications catalog:

• Kubernetes applications = operator-curated platform components.
• Bundles = your services, defined by your repository, built and promoted through Loopback automation.

Mental model

Think in five layers:

1. Connect Git — authorize Loopback to read a repository (GitHub or GitLab, cloud or self-managed).
2. Define a bundle — give that repo a product identity inside Loopback (name, slug, build context).
3. Discover — let Loopback scan the repo for Dockerfile, Helm chart, ports, and build arguments (status progresses through queued → completed / failed).
4. Bind an environment — say which workspace receives deployments for this bundle (dev/stage/prod tracks).
5. Build and deploy — produce OCI images, optionally promote revisions, and roll out to the cluster.

Each layer has its own state and tasks; failures are usually visible as stuck discovery, failed build, or deployment errors.

1. Bundle repository (Git connection)

Purpose
Represents one Git remote Loopback may clone and receive webhooks from.

What it stores conceptually

• Provider — GitHub vs GitLab.
• Clone URL and default branch.
• Webhook configuration — callback URL, secret reference, active flag.
• Access token — stored as a secret; required for API operations and often for private repos.
• Self-hosted base URL when not using the public SaaS.

User actions

• Install the Loopback GitHub App or configure OAuth / tokens according to your operator’s guide.
• Confirm webhooks deliver push events so discovery and builds can trigger automatically.

Failure modes

• Expired tokens → builds cannot pull source.
• Misconfigured webhook secret → events rejected as untrusted.

2. Bundle (application definition)

Purpose
Links one repository to a logical application your teams recognize (“checkout-api”, “pricing-service”).

What you configure

• Name and description — documentation for humans.
• Slug — stable identifier for URLs and automation (often derived for you).
• Discovery — Loopback-populated fields: Dockerfile path, chart path, exposed ports, base image hints.
• Helm chart source — chart living in repo vs external chart URL.
• Build — context directory, Dockerfile path, build args, optional multi-stage target.

User outcome

• A single place in Loopback that answers: “What is this service, where does it live in Git, how do we build it?”

3. Bundle environment (bind to a workspace)

Purpose
Says: this bundle’s “staging” track runs on workspace X.

Why environments exist

• Same bundle, multiple workspaces — mirrors how teams think about dev / stage / prod.
• Lets Loopback keep parallel configuration (values overrides, feature flags) per track.

User checks

• Workspace must already be healthy Kubernetes (bundles target Kubernetes workloads).
• Correct organization boundary — environments are tenant-scoped.

4. Manifests and cluster resources

Bundle environment manifests hold Kubernetes (or Helm-valued) material specific to that environment.

Cluster resource attachments (where exposed) link additional objects your operator expects per environment.

User meaning

• This is where environment-specific Kubernetes nuance lives (resource limits, ingress hosts, secrets references by name).

5. Revisions (what version is deployed)

Purpose
A revision captures a point in time: commit SHA, build outputs, readiness state.

Typical lifecycle

• Revision created when you trigger a build or when automation creates one from a webhook.
• Moves through states such as ready vs failed.
• Deployments pin to a revision (or pick latest ready revision depending on automation path).

User outcome

• You can answer “what commit is prod?” inside Loopback instead of only in CI logs.

6. Images

Bundle images represent OCI images built for a bundle/revision pair.

User relevance

• Links Loopback build outputs to registry locations your operator configured (commonly Harbor-oriented flows in automation helpers).

7. Deployment (rollout)

Purpose
Tracks an actual rollout of an environment’s revision to the bound workspace.

How deployment automation works (high level)

The deploy routine loads bundle, environment, workspace, and parent cluster context, then creates or updates Flux CD custom resources on the parent Kubernetes cluster (the operator-managed cluster associated with your workspace), in a dedicated Flux namespace such as loopback-deployments.

Flux primitives involved include:

• OCIRepository sources pointing at registry URLs.
• HelmRelease objects targeting your workspace namespaces.
• Optional Kustomization layering.

User translation

• Loopback does not only kubectl apply once; it leaves Flux reconciling your bundle continuously from registry-backed sources — aligned with GitOps practice.
• You should see Flux objects owned by Loopback (managed-by: loopback labels in templates).

Undeploy

• Removing a deployment should delete Flux objects and mark the deployment stopped in Loopback’s records.

Build drivers (what might build your image)

Automation includes multiple drivers (implementation detail, but useful for expectations):

• Tekton-oriented pipelines.
• Buildkit builds.
• Kaniko job builds.

Your operator decides which driver is allowed in your tenant. Errors here surface as build task failures with logs in operator tooling.

Suggested end-to-end workflow (happy path)

1. Create or link a bundle repository for your Git org/project.
2. Create a bundle pointing at that repository.
3. Run discovery; fix Dockerfile/chart paths if auto-detection fails.
4. Create a bundle environment bound to the correct workspace.
5. Trigger build → confirm image exists in registry.
6. Create deployment (or let automation promote) → confirm Flux reports Healthy on the management cluster and workloads appear in the workspace namespace.

Security and compliance notes

• Tokens and webhook secrets are highly sensitive — rotate on schedule.
• Self-hosted Git requires TLS trust configuration; corporate CAs must be honored.
• Who can deploy is governed by organization RBAC — align Loopback roles with your change-management process.

When not to use bundles yet

If your operator has not enabled registry, Flux, or build runners, bundles will fail no matter how correct your Git repo is. Fall back to your own CI/CD pushing manifests until the platform is ready.

Related reading

• Kubernetes applications — platform catalog vs your bundles.
• Workspaces — overview
• What gets built