Skip to content

Limitations

Know these before you rely on Capsailer. Each item says what to do instead.

Images

A bundle holds one platform. build downloads linux/amd64 by default, whatever machine you build on. Use --platform linux/arm64 for ARM nodes. A bundle cannot hold several architectures at once, so a cluster that mixes them needs one bundle per architecture, each pushed to its own registry or path. See Platform.

Capsailer does not detect which images a chart needs. It bundles the images you list, nothing more. If one is missing, the chart installs but its pods cannot pull. Render the chart with helm template and list every image. See Finding the images a chart needs.

Private images need a Docker login on the build machine. build reads ~/.docker/config.json. There are no --username or --password options on build.

Charts

Only classic Helm repositories work. A repository must serve an index.yaml over HTTP or HTTPS, without credentials. OCI chart registries (oci://...) and repositories that need a login are not supported by build. Download such a chart with helm pull and install it from the file yourself.

Image rewriting is limited to the chart's top-level values.yaml. These are not rewritten:

  • 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 (for example operator CRs)

Run helm template on the rewritten chart and check that every image: points to your registry. See Rewriting image references.

Rewriting normalizes values.yaml. The file is parsed and written back, so comments are dropped and keys are sorted. The values themselves are unchanged.

Charts are only published to the built-in ChartMuseum. With --external-registry, images are pushed but charts stay in the bundle. Install them from the extracted .tgz. See push.

The Built-In Registry

capsailer registry is meant for getting started and for clusters that have nothing else. It is deliberately simple:

  • No TLS and no authentication. Anyone who can reach the service can read and overwrite images. The service is ClusterIP, so it is only reachable from inside the cluster, but every workload in the cluster can use it. For production use a hardened registry such as Harbor, and push to it with --external-registry.
  • Nodes must be allowed to pull over HTTP. Configure the container runtime on every node to accept the registry as insecure. See Pulling from the registry.
  • One replica, default storage class, two 10Gi volumes. There is no option to change the size or the storage class. Edit the resources with kubectl afterwards if you need to.

Commands

  • push --dry-run works with --bundle only, not with --image.
  • push --image needs a running local Docker daemon.
  • unpack writes into the current directory and overwrites files with the same name.
  • registry and pushes to the built-in registry need kubectl. registry in a cluster without internet access also needs docker if it should load registry:2 from a bundle, and that only helps single-node clusters such as kind or minikube.