CosmoCode

Helm Repositories

Work with Helm chart repositories. Add, search, update, and manage repos for discovering and sharing charts.

6 min read

Helm Repositories

In the previous tutorial, we managed releases and rollbacks. But where do all those charts come from? Helm repositories. Think of them like npm registries or Docker Hub — but for Kubernetes packages.

What Is a Helm Repository?

A Helm repository is simply an HTTP server hosting an index.yaml file and packaged chart archives (.tgz files). That's it. No special software needed.

https://charts.example.com/
├── index.yaml              # Catalog of all charts + versions
├── my-chart-1.0.0.tgz
├── my-chart-1.1.0.tgz
└── another-chart-2.0.0.tgz

The index.yaml contains metadata about every chart version: name, version, description, digest, and download URL.

Adding Repositories

# Add a repository
helm repo add bitnami https://charts.bitnami.com/bitnami

# Add with authentication
helm repo add private https://charts.example.com \
  --username admin \
  --password secret

# Add with a CA certificate
helm repo add corporate https://charts.corp.com \
  --ca-file /path/to/ca.crt

# Add with client certificate authentication
helm repo add secure https://charts.secure.com \
  --cert-file /path/to/client.crt \
  --key-file /path/to/client.key

Popular Repositories

Here are repos you'll use often:

# Bitnami — huge collection of production-ready charts
helm repo add bitnami https://charts.bitnami.com/bitnami

# Prometheus Community — monitoring stack
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

# Grafana — dashboards and observability
helm repo add grafana https://grafana.github.io/helm-charts

# Ingress NGINX
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

# Jetstack — cert-manager
helm repo add jetstack https://charts.jetstack.io

# HashiCorp — Vault, Consul
helm repo add hashicorp https://helm.releases.hashicorp.com

Managing Repositories

# List all configured repos
helm repo list

# NAME              URL
# bitnami           https://charts.bitnami.com/bitnami
# prometheus-community  https://prometheus-community.github.io/helm-charts

# Update cached index (like apt update)
helm repo update

# Update a specific repo
helm repo update bitnami

# Remove a repository
helm repo remove bitnami

"Do I need to repo update before installing?"

Yes, before searching or installing, run helm repo update to fetch the latest chart index. Without it, you're searching stale data.

Searching for Charts

Search Repositories

# Search across all your repos
helm search repo nginx

# NAME                      CHART VERSION  APP VERSION  DESCRIPTION
# bitnami/nginx             15.3.0         1.25.3       NGINX is a web server...
# bitnami/nginx-ingress...  10.2.1         1.9.5        NGINX Ingress Controller...
# ingress-nginx/ingress-..  4.8.3          1.9.4        Ingress controller for...

# Search with version constraints
helm search repo nginx --version "^15.0.0"

# Show all versions (not just latest)
helm search repo nginx --versions

# Show development versions too
helm search repo nginx --devel

Search Artifact Hub

Artifact Hub is the centralized search engine for Helm charts (and other K8s packages):

# Search Artifact Hub from the CLI
helm search hub nginx

# Or just browse https://artifacthub.io

Inspecting Charts Before Installing

Always look before you leap:

# See the chart's README
helm show readme bitnami/nginx

# See the default values.yaml
helm show values bitnami/nginx

# See Chart.yaml metadata
helm show chart bitnami/nginx

# See everything
helm show all bitnami/nginx

# Save values to a file for customization
helm show values bitnami/nginx > my-nginx-values.yaml

The helm show values workflow is especially useful:

# 1. Dump default values
helm show values bitnami/postgresql > postgresql-values.yaml

# 2. Edit to your needs (delete everything you don't need to override)
# Keep only the values you want to change

# 3. Install with your overrides
helm install my-db bitnami/postgresql -f postgresql-values.yaml

Installing from a Repository

# Install latest version
helm install my-nginx bitnami/nginx

# Install a specific version
helm install my-nginx bitnami/nginx --version 15.3.0

# Install with custom values
helm install my-nginx bitnami/nginx -f my-values.yaml

# Install into a specific namespace
helm install my-nginx bitnami/nginx -n web --create-namespace

Pulling Charts Locally

Sometimes you want to download a chart without installing it:

# Download the .tgz archive
helm pull bitnami/nginx

# Download and extract
helm pull bitnami/nginx --untar

# Download a specific version
helm pull bitnami/nginx --version 15.3.0 --untar

# Download to a specific directory
helm pull bitnami/nginx --untar --untardir ./charts/

This is useful for:

  • Auditing a chart's templates before deploying
  • Making local modifications
  • Bundling charts for air-gapped environments
  • Pinning exact chart source in version control

OCI Registries — The Modern Way

Helm 3 supports storing charts in OCI (Open Container Initiative) registries, just like Docker images. This is the future of chart distribution.

Why OCI?

  • No separate index.yaml infrastructure needed
  • Use existing container registry (Docker Hub, ECR, GCR, ACR, GHCR)
  • Built-in signing and verification
  • Consistent tooling across images and charts

Working with OCI Charts

# Login to a registry
helm registry login ghcr.io -u username

# Pull a chart from OCI
helm pull oci://ghcr.io/your-org/my-chart --version 1.0.0

# Install directly from OCI
helm install my-release oci://ghcr.io/your-org/my-chart --version 1.0.0

# Push a chart to OCI (after packaging)
helm push my-chart-1.0.0.tgz oci://ghcr.io/your-org/

# Show chart info from OCI
helm show chart oci://ghcr.io/your-org/my-chart --version 1.0.0

OCI repositories don't use helm repo add. You reference them directly with the oci:// prefix.

OCI in Dependencies

# Chart.yaml
dependencies:
  - name: my-lib
    version: "1.0.0"
    repository: "oci://ghcr.io/your-org"

Private Repositories

Basic Auth

helm repo add private https://charts.company.com \
  --username deploy-bot \
  --password $CHART_REPO_PASSWORD

Token Auth

helm repo add private https://charts.company.com \
  --pass-credentials-all \
  --username "" \
  --password "$GITHUB_TOKEN"

Using GitHub Container Registry

# Login
echo $GITHUB_TOKEN | helm registry login ghcr.io -u USERNAME --password-stdin

# Pull
helm pull oci://ghcr.io/your-org/charts/my-chart --version 1.0.0

Using AWS ECR

# Login (uses AWS CLI credentials)
aws ecr get-login-password --region us-east-1 | \
  helm registry login --username AWS --password-stdin \
  123456789.dkr.ecr.us-east-1.amazonaws.com

# Push
helm push my-chart-1.0.0.tgz oci://123456789.dkr.ecr.us-east-1.amazonaws.com/

Repository Best Practices

  1. Pin chart versions — Never use latest in production. Specify exact versions or at least major version ranges.

  2. Vendor critical charts — For production dependencies, pull charts locally and commit them to your repo:

    helm pull bitnami/postgresql --version 13.2.24
# Commit postgresql-13.2.24.tgz to your repo

  3. Update regularly — Run helm repo update before searching or installing.

  4. Mirror for air-gapped — Use tools like ChartMuseum or Harbor to mirror public charts internally.

  5. Prefer OCI — If your infrastructure supports it, OCI registries are simpler and more robust than traditional HTTP repos.

What's Next?

You now know how to find, add, search, and manage chart repositories — both traditional HTTP repos and modern OCI registries.

In the next tutorial, we'll learn how to package and publish your own charts — turning your charts into shareable packages.

Previous← Managing Releases and RollbacksNextPackaging and Publishing Charts →