build
Downloads container images and Helm charts and packs them into one bundle file. Run it on a machine with internet access.
Usage
What It Does
- Reads and validates the manifest.
- Pulls every image and saves it as a tar file. Four images are pulled at a time.
- Downloads every chart from its Helm repository.
- With
--rewrite-image-references, changes the image names inside each chart to your registry. - Copies values files and the manifest into the bundle.
- Writes everything to a
.tar.gz.
Options
| Option | Description |
|---|---|
--manifest |
Path to the manifest file (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 |
Platform of the images to download, as os/arch[/variant] (default linux/amd64). For example linux/arm64 |
--registry-url |
Registry the cluster will pull from, with an optional path (registry.local:5000, harbor.example.com/nai). Required with --rewrite-image-references |
Platform
A bundle holds one platform. By default that is linux/amd64, whatever machine you build on. For ARM nodes use --platform linux/arm64:
For images that publish several architectures, the matching one is downloaded. An image that is built for a single, different architecture is rejected with a message such as image is built for linux/arm64, not linux/amd64, so you find out at build time and not when the pod fails.
If your cluster mixes architectures, build one bundle per architecture. Pushed names do not include the architecture, so push each bundle to its own registry, or give each its own path so they do not overwrite each other:
capsailer build --manifest manifest.yaml --output amd64.tar.gz --platform linux/amd64 \
--rewrite-image-references --registry-url registry.example.com/amd64
capsailer build --manifest manifest.yaml --output arm64.tar.gz --platform linux/arm64 \
--rewrite-image-references --registry-url registry.example.com/arm64
Each bundle's charts then point at the path that holds the right architecture.
Credentials
Images are pulled with the credentials in ~/.docker/config.json. Run docker login <registry> before building if an image is private. Chart repositories must be classic Helm repositories (an index.yaml over HTTP or HTTPS) that are reachable without credentials. OCI chart registries are not supported.
How Rewriting Works
The registry host in every image reference found in a chart's values.yaml is replaced by --registry-url. The repository path and tag are kept, and Docker Hub official images lose their library/ part:
| In the chart | After rewriting (--registry-url registry.local:5000) |
|---|---|
bitnami/nginx:1.25 |
registry.local:5000/bitnami/nginx:1.25 |
nginx:1.25 |
registry.local:5000/nginx:1.25 |
quay.io/acme/proxy:2.0 |
registry.local:5000/acme/proxy:2.0 |
capsailer push uses the same rule, so the names in the charts and the names in the registry agree. Running build again on an already rewritten chart changes nothing. Values that are not image references (template expressions, chart repository URLs) are left alone.
Only the chart's top-level values.yaml is rewritten. These are not rewritten, so you have to point them at your registry yourself:
- images hard-coded in a template
- defaults that exist only in a subchart's own
values.yaml - images in your own values files and in custom resources
Render the rewritten chart with helm template and check every image: line. The rewrite also normalizes values.yaml: comments are dropped and keys are sorted.
See Limitations.
Examples
# Plain bundle
capsailer build --manifest manifest.yaml --output bundle.tar.gz
# Bundle for ARM nodes
capsailer build --manifest manifest.yaml --output bundle-arm64.tar.gz --platform linux/arm64
# Bundle whose charts use your registry
capsailer build --manifest manifest.yaml --output bundle.tar.gz \
--rewrite-image-references --registry-url registry.local:5000