Helm repositories and OCI registries — the chart distribution model

Helm charts can be distributed through traditional chart repositories or OCI registries. This lesson walks the two models, the migration path, the operational trade-offs, and the discipline.

Traditional Helm repositories

flowchart LR
    A["Chart Museum / Chart repo server"] --> B[index.yaml]
    B --> C[mychart-1.0.0.tgz]
    B --> D[mychart-1.1.0.tgz]
    A -->|HTTP GET| E[Helm client]
    E -->|helm repo add| F[Local repo cache]

A traditional Helm repository:

• Chart repository server. Chart Museum, JFrog Artifactory, a simple HTTP server hosting the charts.
• index.yaml. Lists all charts and their versions.
• Chart tarballs. .tgz files containing the chart.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm install myrelease bitnami/postgresql --version 12.1.0

The client downloads index.yaml, lists available charts and versions, then downloads the specific chart tarball.

OCI registries

flowchart LR
    A["OCI registry: Harbor, GHCR, ECR"] --> B[Chart as OCI artifact]
    B --> C["mychart:1.0.0"]
    B --> D["mychart:1.1.0"]
    A -->|OCI distribution| E[Helm client]
    E -->|helm chart pull| F[Local chart cache]

OCI registries (Helm 3.8+) store charts as OCI artifacts:

• Registry. Harbor, GitHub Container Registry (GHCR), AWS Elastic Container Registry (ECR), Google Container Registry (GCR), Azure Container Registry (ACR).
• Authentication. Built-in (basic auth, OIDC, IAM).
• Signing. Built-in (cosign, Notary v2).
• Version discovery. OCI tags and labels.

helm chart save mychart/ oci://registry.example.com/charts/mychart:1.0.0
helm chart push oci://registry.example.com/charts/mychart:1.0.0
helm install myrelease oci://registry.example.com/charts/mychart --version 1.0.0

The helm chart save command packages the chart as an OCI artifact; helm chart push pushes it to the registry; helm install pulls from the registry.

The migration path

flowchart LR
    A[Traditional repo] --> B[helm chart pull]
    B --> C[Local tarball]
    C --> D[helm chart save to OCI]
    D --> E[OCI registry]
    E --> F[helm chart push]

Migrating from traditional to OCI:

1. Pull each chart from the traditional repo: helm chart pull bitnami/postgresql:12.1.0.
2. Save to OCI: helm chart save ...tgz oci://registry/chart:1.0.0.
3. Push to the OCI registry: helm chart push.

Or use a tool like chart-replacer or helm-controller to automate the migration.

Chart signing

# Sign with cosign
cosign sign --key cosign.key registry.example.com/charts/mychart:1.0.0

# Verify
cosign verify --key cosign.pub registry.example.com/charts/mychart:1.0.0

Chart signing (with cosign or Notary v2) provides:

• Authenticity. The chart was signed by the claimed signer.
• Integrity. The chart has not been modified since signing.

Production deployments should sign and verify charts.

The operational trade-offs

flowchart LR
    A[Traditional repos] --> B["+ Simple, well-understood"]
    A --> C[- No built-in auth or signing]
    A --> D[- No unified discovery]
    E[OCI registries] --> F[+ Unified auth and signing]
    E --> G[+ Unified with container images]
    E --> H[+ Better discovery]
    E --> I[- Migration effort]
    E --> J[- Requires Helm 3.8+]

The trade-offs:

Traditional:

• Pros: Simple, well-understood.
• Cons: No built-in auth or signing; no unified discovery.

OCI:

• Pros: Unified auth and signing; unified with container images; better discovery.
• Cons: Migration effort; requires Helm 3.8+.

Quiz

The operational discipline

Chart distribution in production rests on five non-negotiable elements:

• Pin chart versions. Never use latest in production.
• Sign charts. Sign with cosign or Notary v2 before publishing.
• Verify signatures. Verify the signature before installing in production.
• Use a trusted registry. OCI registry with proper authentication.
• Audit the registry. Monitor who pushes to the registry; alert on unknown charts.

Charts are production artefacts. Treat them with the same rigour as container images: pin, sign, verify, audit.