Skip to content

Building Bundles

capsailer build turns a manifest into one portable file. Run it on a machine with internet access.

Basic Bundle Creation

capsailer init --manifest manifest.yaml     # optional check
capsailer build --manifest manifest.yaml --output capsailer-bundle.tar.gz

What Happens During the Build

  1. The manifest is read and validated.
  2. Every image is pulled and saved as a tar file (four at a time).
  3. Every chart is downloaded from its repository.
  4. With --rewrite-image-references, the image names inside each chart are changed to your registry.
  5. Values files are copied next to the charts, and the manifest is copied into the bundle.
  6. Everything is packed into one .tar.gz.

Build Options

Option Description
--manifest Manifest to read (default manifest.yaml)
--output Bundle file to write (default capsailer-bundle.tar.gz)
--rewrite-image-references Rewrite image names in the charts to use --registry-url
--platform Image platform, os/arch[/variant] (default linux/amd64). Use linux/arm64 for ARM nodes
--registry-url Registry (with optional path) the cluster will pull from. Required with --rewrite-image-references 
capsailer build --manifest manifest.yaml --output my-bundle.tar.gz

Image downloads use the credentials in ~/.docker/config.json, so run docker login <registry> for private images. Chart repositories must be reachable without credentials.

Rewriting Image References

For air-gapped deployments, you often need to rewrite container image references in Helm charts to point to your private registry. Capsailer can do this automatically during the build process:

# Build a bundle with image reference rewriting
capsailer build --manifest manifest.yaml --output bundle.tar.gz --rewrite-image-references --registry-url registry.local:5000

This will: - Download all images and charts specified in the manifest - Rewrite all image references in Helm charts to use your private registry - Package everything into a portable bundle

When you deploy these charts in your air-gapped environment, they will automatically use images from your private registry without requiring any manual modifications.

Images keep their repository path and tag, and capsailer push creates exactly the names the charts ask for. See How image names are mapped.

Including Operator Images

When building bundles that include Kubernetes operators, you need to consider both the operator images themselves and the images referenced in the operator's Custom Resources (CRs):

# Example manifest.yaml for an operator
images:
  # The operator image itself
  - quay.io/example/postgres-operator:v1.10.0

  # Images that the operator will deploy via CRs
  - docker.io/postgres:14.5
  - docker.io/postgres:14.6
  - docker.io/postgres-exporter:0.10.0

charts:
  - name: postgres-operator
    repo: https://example.com/charts
    version: 1.10.0

Tips for Operator Bundles

  1. Identify All Required Images: Review the operator documentation to identify all container images that might be deployed by the operator's CRs.

  2. Include Related Tools: Many operators deploy additional components like exporters, sidecars, or init containers. Make sure to include these images in your manifest.

  3. Version Consistency: Ensure that the versions of the operator and the images it deploys are compatible with each other.

  4. Check CR Templates: If the operator's Helm chart includes CR templates, Capsailer's image reference rewriting will automatically update those references.

Bundle Contents

A bundle is a gzipped tar file with this layout:

images/
  nginx_1.16.0.tar          one docker-archive tar per image
charts/
  hello-world-0.1.0.tgz     the charts (rewritten if you asked for it)
  hello-values.yaml         values files from the manifest, if any
manifest.yaml               a copy of your manifest

You can look inside with standard tools, or extract it with capsailer unpack --file bundle.tar.gz. unpack writes into the current directory, so run it in an empty one.

Bundle Size

The bundle holds every image layer, so size follows the images you list. To keep it small:

  • List only the images you need.
  • Pin tags, so you do not download extra versions.
  • Prefer slim base images where you have a choice.