Pushing and Pulling Charts

helm push helm pull Chart Versioning Dependencies

A comprehensive guide to pushing and pulling Helm charts covering helm push, helm pull, chart versioning, dependency management, and best practices for chart distribution.

helm push helm pull Chart Versioning Dependencies

Chart Distribution Workflow

The Helm chart distribution workflow involves packaging, pushing to a repository, and pulling for installation. This guide covers the complete lifecycle of chart distribution.

helm package: Package a chart into a .tgz file
helm push: Push a packaged chart to a repository
helm pull: Download a chart from a repository
helm dependency: Manage chart dependencies
Chart Versioning: Semantic versioning for charts

Key Concept: Pushing and pulling charts is the core of Helm's distribution model. It enables sharing, versioning, and reusing charts across teams and organizations.

Packaging Charts

                # Package a chart
helm package ./my-chart

# Package with specific version
helm package ./my-chart --version 1.2.3

# Package and sign
helm package ./my-chart --sign --key 'my-key'

# Package with app version override
helm package ./my-chart --app-version 2.0.0

# Package with dependency update
helm dependency update ./my-chart
helm package ./my-chart

# Package all charts in a directory
for chart in ./charts/*; do
  helm package "$chart"
done

# Package and output to specific directory
helm package ./my-chart --destination ./dist

# View packaged chart contents
tar -tzf my-chart-1.0.0.tgz
            

Packaging Best Practices:

Always update dependencies before packaging
Use semantic versioning for chart versions
Test charts before packaging (helm lint)
Sign charts for security
Use consistent destination directories

Pushing Charts to Repositories

                # Push to traditional Helm repository
helm push my-chart-1.0.0.tgz my-repo

# Push to OCI registry
helm push my-chart-1.0.0.tgz oci://myregistry.azurecr.io/helm

# Push with tag
helm push my-chart-1.0.0.tgz oci://myregistry.azurecr.io/helm/my-chart:1.0.0

# Push to GitHub Container Registry
helm push my-chart-1.0.0.tgz oci://ghcr.io/username/helm

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

# Push to Azure ACR
helm push my-chart-1.0.0.tgz oci://myregistry.azurecr.io/helm

# Push with authentication (traditional repo)
curl --data-binary "@my-chart-1.0.0.tgz" \
  -u username:password \
  https://myrepo.com/api/charts

# Push with Chartmuseum
curl --data-binary "@my-chart-1.0.0.tgz" \
  http://chartmuseum:8080/api/charts
            

Traditional Repo

Uses HTTP/HTTPS with index.yaml. Requires authentication with basic auth.

Command: helm push <chart> <repo>

OCI Registry

Uses OCI protocol. Charts stored alongside images. Uses docker login authentication.

Command: helm push <chart> oci://<registry>/<repo>

Push Considerations:

Ensure you're logged in to the registry
Chart must be packaged before pushing
Use semver for chart versions
Check registry permissions
Avoid overwriting existing versions

Pulling Charts from Repositories

                # Pull from repository
helm pull my-repo/my-chart

# Pull specific version
helm pull my-repo/my-chart --version 1.0.0

# Pull and untar
helm pull my-repo/my-chart --untar

# Pull to specific directory
helm pull my-repo/my-chart --destination ./downloads

# Pull from OCI registry
helm pull oci://myregistry.azurecr.io/helm/my-chart --version 1.0.0

# Pull and untar from OCI
helm pull oci://myregistry.azurecr.io/helm/my-chart --version 1.0.0 --untar

# Pull with authentication (traditional repo)
helm pull my-repo/my-chart --username user --password pass

# Pull all charts in a repository
helm search repo my-repo --versions | awk '{print $1}' | xargs -I {} helm pull {}

# Pull chart and verify signature
helm pull my-repo/my-chart --verify
            

helm pull

Download a chart to your local machine. Useful for offline installations or debugging.

--untar

Extract the chart after downloading. Useful for inspecting chart contents.

--version

Specify the chart version to pull. Defaults to latest.

--destination

Specify the output directory for the downloaded chart.

Pull Best Practices:

Use specific versions for production pulls
Validate chart integrity after pull
Use --untar for inspection before installation
Store charts in a local cache for offline use
Verify signatures for security

Chart Versioning

Semantic versioning (SemVer) is essential for chart management. It helps track changes and manage dependencies.

Version Change	Meaning	Example
Major (X.0.0)	Breaking changes. Incompatible with previous versions.	1.0.0 → 2.0.0
Minor (0.Y.0)	New features. Backward compatible.	1.0.0 → 1.1.0
Patch (0.0.Z)	Bug fixes. Backward compatible.	1.0.0 → 1.0.1
Pre-release	Alpha, beta, or RC versions.	1.0.0-alpha.1
Build Metadata	Build-specific metadata.	1.0.0+2023.01.15

                # Versioning examples
# Chart.yaml
version: 1.0.0          # Stable release
version: 1.1.0-beta.1   # Beta release
version: 1.1.0-rc.1     # Release candidate
version: 1.1.0+2023.01.15  # With build metadata

# Update version during packaging
helm package ./my-chart --version 1.2.0

# Update app version
helm package ./my-chart --app-version 2.3.0

# Check chart version
helm show chart my-repo/my-chart

# List available versions
helm search repo my-repo/my-chart --versions

# Version constraints in dependencies
dependencies:
  - name: postgresql
    version: ">=1.0.0 <2.0.0"  # Allow 1.x.x only
  - name: redis
    version: "^16.0.0"         # Allow 16.x.x only
  - name: mongodb
    version: "~12.0.0"         # Allow 12.0.x only
            

Versioning Best Practices:

Follow semantic versioning strictly
Use pre-release versions for testing
Document breaking changes in major versions
Use version constraints for dependencies
Keep version and appVersion synchronized

Dependency Management

                # Chart.yaml with dependencies
dependencies:
  - name: postgresql
    version: 11.0.0
    repository: https://charts.bitnami.com/bitnami
  - name: redis
    version: 16.0.0
    repository: https://charts.bitnami.com/bitnami
  - name: mongodb
    version: 12.0.0
    repository: oci://myregistry.azurecr.io/helm

# Update dependencies
helm dependency update

# Build dependencies
helm dependency build

# List dependencies
helm dependency list

# Update specific dependency
helm dependency update --skip-refresh

# Use dependency with alias
dependencies:
  - name: postgresql
    version: 11.0.0
    repository: https://charts.bitnami.com/bitnami
    alias: db

# Use dependency with condition
dependencies:
  - name: redis
    version: 16.0.0
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled

# Use dependency with tags
dependencies:
  - name: mongodb
    version: 12.0.0
    repository: https://charts.bitnami.com/bitnami
    tags:
      - database
      - backend

# Override dependency values
# values.yaml
postgresql:
  postgresqlDatabase: myapp
  postgresqlUsername: myuser
  postgresqlPassword: secret
            

Dependency Best Practices:

Pin specific versions for stability
Use conditions for optional dependencies
Use aliases to avoid conflicts
Update dependencies regularly
Test dependency combinations

CI/CD Integration

                # GitHub Actions workflow for push
name: Push Helm Chart
on:
  push:
    tags:
      - 'v*'

jobs:
  push:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Install Helm
      uses: azure/setup-helm@v3
    
    - name: Login to OCI
      run: |
        echo "${{ secrets.REGISTRY_TOKEN }}" | \
          helm registry login myregistry.azurecr.io -u ${{ secrets.REGISTRY_USER }} --password-stdin
    
    - name: Package and Push
      run: |
        helm package ./my-chart --version ${GITHUB_REF#refs/tags/v}
        helm push my-chart-*.tgz oci://myregistry.azurecr.io/helm

# GitLab CI
stages:
  - package
  - push

package:
  stage: package
  image: alpine/helm:latest
  script:
    - helm package ./my-chart
  artifacts:
    paths:
      - my-chart-*.tgz

push:
  stage: push
  image: alpine/helm:latest
  before_script:
    - echo $REGISTRY_PASSWORD | helm registry login $REGISTRY_URL -u $REGISTRY_USER --password-stdin
  script:
    - helm push my-chart-*.tgz oci://$REGISTRY_URL/$PROJECT_PATH

# Jenkins Pipeline
pipeline {
    agent any
    stages {
        stage('Package') {
            steps {
                sh 'helm package ./my-chart'
            }
        }
        stage('Push') {
            steps {
                withCredentials([
                    string(credentialsId: 'registry-token', variable: 'TOKEN')
                ]) {
                    sh '''
                        echo $TOKEN | helm registry login myregistry.azurecr.io -u $USER --password-stdin
                        helm push my-chart-*.tgz oci://myregistry.azurecr.io/helm
                    '''
                }
            }
        }
    }
}
            

CI/CD Integration Tips:

Use tags for versioning releases
Automate packaging and pushing
Use secrets for credentials
Run helm lint before packaging
Test charts before pushing

Frequently Asked Questions

What is the difference between helm push and helm package?

helm package creates a .tgz file from a chart directory. helm push uploads a packaged chart to a repository. You need to package first, then push.

How do I push a chart to a traditional Helm repository?

Use helm push <chart.tgz> <repo-name>. Ensure the repository is added with helm repo add and you have push permissions.

What is the difference between helm pull and helm fetch?

helm pull is the modern command (replaces helm fetch). Both download charts, but helm pull is the recommended command in Helm v3.

How do I push a chart to an OCI registry?

Use helm push <chart.tgz> oci://<registry>/<repo>. Ensure you're logged in with helm registry login.

How do I version charts?

Follow semantic versioning (MAJOR.MINOR.PATCH). Update the version field in Chart.yaml or use --version flag during packaging.

How do I update chart dependencies?

Use helm dependency update to download and update dependencies. Use helm dependency build to build from Chart.lock.

Can I push charts to multiple repositories?

Yes! You can push the same chart to multiple repositories by running helm push for each repository. This is useful for distribution and backup.

How do I verify a pulled chart?

Use helm pull --verify to verify the chart's signature. Also, you can inspect the chart with helm show chart and helm show values.

Pushing and Pulling Charts

Traditional Repo

OCI Registry

helm pull

--untar

--version

--destination

What is Helm?

Helm Repositories

OCI Repositories

Upgrade & Rollback

Helm Best Practices