Skip to content

Getting Started

This guide takes you from nothing to an installed Helm chart that uses images from your own registry. It needs no Kubernetes cluster, so you can try it on a laptop. Afterwards you will know how to repeat the steps for a real air-gapped cluster.

What you need

  • The capsailer binary. See Installation.
  • A registry to push to. For this guide, start a local one with Docker:
docker run -d -p 5000:5000 --name registry registry:2

Any registry works. If you have Harbor or Artifactory, use it instead and replace localhost:5000 below. - helm, for the last step only.

1. Describe what you want

Create manifest.yaml:

images:
  - nginx:1.16.0

charts:
  - name: hello-world
    repo: https://helm.github.io/examples
    version: 0.1.0

The chart starts nginx:1.16.0, so that image is listed too. A chart only works offline if every image it starts is in the bundle. Creating Manifests shows how to find them.

Check the file:

capsailer init --manifest manifest.yaml

Manifest is valid. Found 1 images and 1 charts.

2. Build the bundle

Run this on a machine with internet access:

capsailer build --manifest manifest.yaml --output bundle.tar.gz \
  --rewrite-image-references --registry-url localhost:5000

--registry-url is the address your cluster will pull images from. Capsailer writes it into the charts, so no one has to edit them later.

The result is one file, bundle.tar.gz. It holds the images, the charts and a copy of the manifest.

Images are downloaded for linux/amd64. If your cluster runs on ARM, add --platform linux/arm64. See Platform.

3. Move it across

In a real setup you now copy bundle.tar.gz and the capsailer binary to the air-gapped side, for example with scp or a USB drive. For this guide, stay where you are.

4. Push the images

First look at what would happen:

capsailer push --bundle bundle.tar.gz --external-registry localhost:5000 --dry-run

  nginx:1.16.0 -> localhost:5000/nginx:1.16.0
Dry run: nothing was pushed

Then push:

capsailer push --bundle bundle.tar.gz --external-registry localhost:5000

Check the registry:

curl localhost:5000/v2/_catalog
# {"repositories":["nginx"]}

5. Install the chart

Extract the bundle into an empty directory. unpack writes to the current directory:

mkdir work && cd work
capsailer unpack --file ../bundle.tar.gz

helm template my-hello charts/hello-world-0.1.0.tgz | grep image:
#   image: "localhost:5000/nginx:1.16.0"

helm install my-hello charts/hello-world-0.1.0.tgz

The chart asks for localhost:5000/nginx:1.16.0, which is the name push created. That is the point of Capsailer: the names in the charts and the names in the registry agree without any manual editing.

Using it for real

For a real air-gapped cluster, two things change:

  • The registry address. Use --registry-url with the address the cluster nodes pull from, not localhost. Use the same host (and path, if any) as --external-registry when you push. See How image names are mapped.
  • Where the registry lives. You can push to a registry you already run, or let Capsailer deploy one in the cluster with capsailer registry. The second option also publishes your charts to a ChartMuseum. See Air-Gapped Deployment.

Next steps