Skip to content

Creating Manifests

A manifest is a YAML file that lists the container images and Helm charts you want in your bundle. It is the only input capsailer build needs.

Manifest Structure

images:
  - nginx:1.16.0
  - quay.io/prometheus/node-exporter:v1.8.2

charts:
  - name: hello-world
    repo: https://helm.github.io/examples
    version: 0.1.0
    valuesFile: hello-values.yaml   # optional

A manifest needs at least one image or one chart. The default file name is manifest.yaml; use --manifest to pick another.

Images Section

images is a list of images in the usual repository:tag form. Docker Hub is assumed when no registry is given.

images:
  - nginx:1.25.0                       # Docker Hub official image
  - grafana/grafana:10.4.2             # Docker Hub with namespace
  - quay.io/prometheus/prometheus:v2.53.0
  - registry.example.com/team/app:1.4  # private registry (needs docker login)

Charts Section

charts is a list of Helm charts from a classic Helm repository (one with an index.yaml served over HTTP or HTTPS, without credentials). OCI chart registries (oci://...) are not supported; use helm pull and install such a chart from the file. Each entry needs:

  • name: the chart name
  • repo: the URL of the Helm repository
  • version: the exact chart version

Optionally:

  • valuesFile: path to a values file to include in the bundle (see Values Files)

Finding the Images a Chart Needs

Capsailer downloads the images and charts you list. It does not read a chart to work out which images it starts. If an image is missing from the bundle, the chart installs but its pods cannot pull the image.

To find the images a chart uses, render it on the connected machine:

helm repo add examples https://helm.github.io/examples
helm template my-hello examples/hello-world --version 0.1.0 | grep "image:"
#   image: "nginx:1.16.0"

Add every image you see to the images list. Use -f your-values.yaml when you render, so images that depend on your settings are included. Charts with optional components (metrics exporters, init containers) only show those images when the component is enabled.

Tips

  • Pin tags. Write nginx:1.25.0, not nginx or nginx:latest. A pinned tag gives you the same bundle every time.
  • Architecture. Images are downloaded for linux/amd64 unless you pass build --platform. See Platform.
  • Private images. build reads credentials from ~/.docker/config.json. Run docker login <registry> first. Chart repositories must be reachable without credentials.
  • Check Docker Hub namespaces. Some publishers move images. For example, Bitnami images that used to live under bitnami/ now live under bitnamilegacy/, so older Bitnami chart versions point at images that no longer exist. Render the chart and try the images before you build.

Values Files

valuesFile copies the file into the bundle next to the chart. It is not applied automatically. Pass it to Helm yourself when you install:

helm install my-hello charts/hello-world-0.1.0.tgz -f hello-values.yaml

Validating a Manifest

Before building a bundle, you can validate your manifest file using the init command:

capsailer init --manifest manifest.yaml

This checks that the manifest is valid YAML, has at least one image or chart, that every chart has a name, repo and version, and that each valuesFile exists. It does not contact the network, so it does not prove an image or chart exists. build finds that out.