Complete Guide: Setting Up and Publishing Helm Charts to ChartMuseum#

ChartMuseum is an open-source Helm Chart Repository server that makes it easy to host and share Helm charts within your organization. This comprehensive guide covers everything from setting up ChartMuseum to automating chart publishing through CI/CD pipelines.

1. Setting Up ChartMuseum#

Install ChartMuseum in Kubernetes#

First, add the ChartMuseum Helm repository and install it with the API enabled for chart uploads:

1
# Add ChartMuseum's Helm repo
2
helm repo add chartmuseum https://chartmuseum.github.io/charts
3

4
# Install ChartMuseum with API enabled for uploads
5
helm install chartmuseum chartmuseum/chartmuseum \
6
  --set env.open.DISABLE_API=false \
7
  --set service.type=ClusterIP \
8
  --set persistence.enabled=true \
9
  --set persistence.size=10Gi
10

11
# For external access, set up an Ingress
12
kubectl create ingress chartmuseum \
13
  --rule="cm.yourdomain.com/*=chartmuseum:8080"

Verify Installation#

Ensure ChartMuseum is running correctly:

1
# Check ChartMuseum is running
2
kubectl get pods -l app.kubernetes.io/name=chartmuseum
3

4
# Test the endpoint
5
curl https://cm.yourdomain.com/health

Advanced Configuration Options#

For production deployments, consider these additional settings:

1
# values.yaml for production deployment
2
env:
3
  open:
4
    DISABLE_API: false
5
    AUTH_ANONYMOUS_GET: true # Allow anonymous chart downloads
6
    BASIC_AUTH_USER: admin
7
    BASIC_AUTH_PASS: secretpassword
8
    DEPTH: 2 # Allow nested chart directories
9

10
persistence:
11
  enabled: true
12
  size: 50Gi
13
  storageClass: fast-ssd
14

15
ingress:
16
  enabled: true
17
  annotations:
18
    cert-manager.io/cluster-issuer: letsencrypt-prod
19
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
20
  hosts:
21
    - cm.yourdomain.com
22
  tls:
23
    - secretName: chartmuseum-tls
24
      hosts:
25
        - cm.yourdomain.com

2. Creating a Helm Chart#

Generate a New Chart#

1
# Create a new chart
2
helm create mychart
3

4
# Structure
5
mychart/
6
  ├── .helmignore   # Files to ignore when packaging
7
  ├── Chart.yaml    # Chart metadata
8
  ├── values.yaml   # Default configuration values
9
  ├── charts/       # Dependencies
10
  └── templates/    # K8s resource templates

Configure Chart Metadata#

Edit Chart.yaml to set appropriate metadata:

1
apiVersion: v2
2
name: mychart
3
description: My application chart
4
type: application
5
version: 0.1.0
6
appVersion: "1.0.0"
7
keywords:
8
  - app
9
  - microservice
10
home: https://github.com/yourorg/mychart
11
sources:
12
  - https://github.com/yourorg/mychart
13
maintainers:
14
  - name: Anubhav Gain
15
    email: anubhav@example.com
16
    url: https://github.com/anubhavg-icpl
17
icon: https://example.com/mychart-icon.png
18
annotations:
19
  category: Backend

Best Practices for Chart Development#

Use Helper Templates: Create _helpers.tpl for reusable template snippets
Implement Health Checks: Include readiness and liveness probes
Resource Limits: Set default CPU/memory limits in values.yaml
Security Context: Define security contexts for pods
Documentation: Include comprehensive README.md and NOTES.txt

3. Packaging the Chart#

Basic Packaging#

1
# Package the chart
2
helm package ./mychart
3

4
# This creates: mychart-0.1.0.tgz

Signed Charts for Enhanced Security#

Setting up GPG signing for charts:

1
# First, set up GPG keys if needed
2
gpg --full-generate-key
3

4
# Choose:
5
# - RSA and RSA (default)
6
# - Key size: 4096
7
# - Validity: 2y
8
# - Real name: Your Name
9
# - Email: your.email@example.com
10

11
# Export keys to format Helm can use
12
gpg --export > ~/.gnupg/pubring.gpg
13
gpg --export-secret-keys > ~/.gnupg/secring.gpg
14

15
# Package with signing
16
helm package ./mychart --sign --key "Your Name <your.email@example.com>"
17

18
# This creates:
19
# - mychart-0.1.0.tgz
20
# - mychart-0.1.0.tgz.prov (provenance file)
21

22
# Verify package
23
helm verify mychart-0.1.0.tgz

Advanced Packaging Options#

1
# Package with custom destination
2
helm package ./mychart --destination ./dist
3

4
# Package with dependency update
5
helm dependency update ./mychart
6
helm package ./mychart
7

8
# Package with version override
9
helm package ./mychart --version 1.2.3
10

11
# Package with app version override
12
helm package ./mychart --app-version 2.0.0

4. Pushing to ChartMuseum#

Method 1: Using the Helm CM-Push Plugin#

The most convenient method using the official plugin:

1
# Install the ChartMuseum plugin
2
helm plugin install https://github.com/chartmuseum/helm-push
3

4
# Add your ChartMuseum repo
5
helm repo add myrepo https://cm.yourdomain.com
6

7
# Push the chart
8
helm cm-push mychart-0.1.0.tgz myrepo
9

10
# Push with force flag to overwrite
11
helm cm-push mychart-0.1.0.tgz myrepo --force
12

13
# Push directly from chart directory
14
helm cm-push ./mychart myrepo

Method 2: Using cURL#

For environments where the plugin isn’t available:

1
# Push chart using cURL
2
curl --data-binary "@mychart-0.1.0.tgz" https://cm.yourdomain.com/api/charts
3

4
# If you've signed the chart, also push the .prov file
5
curl --data-binary "@mychart-0.1.0.tgz.prov" https://cm.yourdomain.com/api/prov
6

7
# If authentication is required
8
curl -u username:password --data-binary "@mychart-0.1.0.tgz" https://cm.yourdomain.com/api/charts
9

10
# With Bearer token authentication
11
curl -H "Authorization: Bearer ${TOKEN}" --data-binary "@mychart-0.1.0.tgz" https://cm.yourdomain.com/api/charts

Method 3: Using CI/CD Integration#

Example for pushing from CI/CD:

1
# Function to push chart with retry
2
push_chart() {
3
    local chart_file=$1
4
    local repo_url=$2
5
    local max_attempts=3
6
    local attempt=1
7

8
    while [ $attempt -le $max_attempts ]; do
9
        echo "Attempting to push $chart_file (attempt $attempt/$max_attempts)"
10

11
        if curl --fail --data-binary "@${chart_file}" "${repo_url}/api/charts"; then
12
            echo "Successfully pushed $chart_file"
13
            return 0
14
        fi
15

16
        attempt=$((attempt + 1))
17
        sleep 5
18
    done
19

20
    echo "Failed to push $chart_file after $max_attempts attempts"
21
    return 1
22
}
23

24
# Usage
25
push_chart "mychart-0.1.0.tgz" "https://cm.yourdomain.com"

5. Managing Charts in ChartMuseum#

Searching and Listing Charts#

1
# Update your local repo to see new charts
2
helm repo update
3

4
# Search for your chart
5
helm search repo myrepo/mychart
6

7
# View chart details
8
helm show chart myrepo/mychart
9

10
# View chart values
11
helm show values myrepo/mychart
12

13
# List all versions
14
helm search repo myrepo/mychart --versions
15

16
# List all charts in repo
17
helm search repo myrepo/

Chart Version Management#

1
# Delete a specific chart version
2
curl -X DELETE https://cm.yourdomain.com/api/charts/mychart/0.1.0
3

4
# Delete all versions of a chart
5
curl -X DELETE https://cm.yourdomain.com/api/charts/mychart
6

7
# Get chart information via API
8
curl https://cm.yourdomain.com/api/charts/mychart
9

10
# Get specific version info
11
curl https://cm.yourdomain.com/api/charts/mychart/0.1.0

Downloading Charts#

1
# Download a chart
2
helm pull myrepo/mychart
3

4
# Download specific version
5
helm pull myrepo/mychart --version 0.1.0
6

7
# Download and untar
8
helm pull myrepo/mychart --untar
9

10
# Download to specific directory
11
helm pull myrepo/mychart --destination ./downloads

6. Automating with CI/CD#

GitHub Actions Workflow#

Create .github/workflows/release.yml:

1
name: Release Charts
2

3
on:
4
  push:
5
    branches: [main]
6
    paths:
7
      - "charts/**"
8

9
jobs:
10
  release:
11
    runs-on: ubuntu-latest
12
    steps:
13
      - name: Checkout
14
        uses: actions/checkout@v3
15
        with:
16
          fetch-depth: 0
17

18
      - name: Configure Git
19
        run: |
20
          git config user.name "$GITHUB_ACTOR"
21
          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
22

23
      - name: Set up Helm
24
        uses: azure/setup-helm@v3
25
        with:
26
          version: v3.12.0
27

28
      - name: Add Helm Push Plugin
29
        run: helm plugin install https://github.com/chartmuseum/helm-push
30

31
      - name: Add ChartMuseum Repo
32
        run: |
33
          helm repo add myrepo https://cm.yourdomain.com \
34
            --username ${{ secrets.CHARTMUSEUM_USER }} \
35
            --password ${{ secrets.CHARTMUSEUM_PASS }}
36

37
      - name: Package and Push Charts
38
        run: |
39
          for chart in ./charts/*; do
40
            if [ -d "$chart" ]; then
41
              echo "Processing chart: $chart"
42

43
              # Update dependencies
44
              helm dependency update "$chart"
45

46
              # Package the chart
47
              helm package "$chart"
48

49
              # Get chart name and version
50
              chart_name=$(basename "$chart")
51
              chart_version=$(grep '^version:' "$chart/Chart.yaml" | awk '{print $2}')
52
              chart_file="${chart_name}-${chart_version}.tgz"
53

54
              # Push to ChartMuseum
55
              helm cm-push "$chart_file" myrepo --force
56

57
              # Clean up
58
              rm -f "$chart_file"
59
            fi
60
          done
61

62
      - name: Update Helm Repo Index
63
        run: helm repo update

GitLab CI Pipeline#

Create .gitlab-ci.yml:

1
stages:
2
  - package
3
  - publish
4

5
variables:
6
  HELM_VERSION: "3.12.0"
7
  CHARTMUSEUM_URL: "https://cm.yourdomain.com"
8

9
package-charts:
10
  stage: package
11
  image: alpine/helm:${HELM_VERSION}
12
  script:
13
    - helm plugin install https://github.com/chartmuseum/helm-push
14
    - |
15
      for chart in ./charts/*; do
16
        if [ -d "$chart" ]; then
17
          helm dependency update "$chart"
18
          helm package "$chart" --destination ./dist
19
        fi
20
      done
21
  artifacts:
22
    paths:
23
      - dist/*.tgz
24
    expire_in: 1 hour
25

26
publish-charts:
27
  stage: publish
28
  image: alpine/helm:${HELM_VERSION}
29
  dependencies:
30
    - package-charts
31
  script:
32
    - helm plugin install https://github.com/chartmuseum/helm-push
33
    - helm repo add myrepo ${CHARTMUSEUM_URL} --username ${CHARTMUSEUM_USER} --password ${CHARTMUSEUM_PASS}
34
    - |
35
      for chart in ./dist/*.tgz; do
36
        helm cm-push "$chart" myrepo --force
37
      done
38
  only:
39
    - main

Jenkins Pipeline#

1
pipeline {
2
    agent any
3

4
    environment {
5
        CHARTMUSEUM_URL = 'https://cm.yourdomain.com'
6
        CHARTMUSEUM_CREDS = credentials('chartmuseum-credentials')
7
    }
8

9
    stages {
10
        stage('Setup') {
11
            steps {
12
                sh '''
13
                    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
14
                    helm plugin install https://github.com/chartmuseum/helm-push
15
                '''
16
            }
17
        }
18

19
        stage('Package Charts') {
20
            steps {
21
                sh '''
22
                    for chart in ./charts/*; do
23
                        if [ -d "$chart" ]; then
24
                            helm dependency update "$chart"
25
                            helm package "$chart"
26
                        fi
27
                    done
28
                '''
29
            }
30
        }
31

32
        stage('Publish Charts') {
33
            steps {
34
                sh '''
35
                    helm repo add myrepo ${CHARTMUSEUM_URL} \
36
                        --username ${CHARTMUSEUM_CREDS_USR} \
37
                        --password ${CHARTMUSEUM_CREDS_PSW}
38

39
                    for chart in *.tgz; do
40
                        helm cm-push "$chart" myrepo --force
41
                    done
42
                '''
43
            }
44
        }
45
    }
46

47
    post {
48
        always {
49
            cleanWs()
50
        }
51
    }
52
}

7. Troubleshooting Common Issues#

API Disabled#

If you get “not found” or 404 errors when pushing:

1
# Check if API is enabled
2
curl https://cm.yourdomain.com/api/charts
3

4
# Fix: Update ChartMuseum deployment
5
kubectl set env deployment/chartmuseum DISABLE_API=false
6

7
# Or edit the deployment
8
kubectl edit deployment chartmuseum
9
# Add under spec.template.spec.containers[0].env:
10
# - name: DISABLE_API
11
#   value: "false"

Authentication Issues#

If authentication is required:

1
# Set credentials in environment
2
export HELM_REPO_USERNAME=admin
3
export HELM_REPO_PASSWORD=password
4

5
# Then push
6
helm cm-push mychart-0.1.0.tgz myrepo
7

8
# Or use inline credentials
9
helm repo add myrepo https://cm.yourdomain.com --username admin --password password
10

11
# For bearer token auth
12
export HELM_REPO_ACCESS_TOKEN=your-token
13
helm cm-push mychart-0.1.0.tgz myrepo

GPG Key Issues#

If chart signing fails:

1
# Check available keys
2
gpg --list-secret-keys --keyid-format LONG
3

4
# Export keys in the format Helm expects
5
gpg --export > ~/.gnupg/pubring.gpg
6
gpg --export-secret-keys > ~/.gnupg/secring.gpg
7
chmod 600 ~/.gnupg/pubring.gpg ~/.gnupg/secring.gpg
8

9
# If using GPG 2.1+, you might need legacy format
10
gpg --export-secret-keys --armor > private.key
11
gpg --export --armor > public.key

Chart Already Exists#

If you get an error about chart already existing:

1
# Use --force flag
2
helm cm-push mychart-0.1.0.tgz myrepo --force
3

4
# Or delete the old version first
5
curl -X DELETE https://cm.yourdomain.com/api/charts/mychart/0.1.0
6

7
# Then push the new version
8
helm cm-push mychart-0.1.0.tgz myrepo

Large Chart Files#

For charts larger than default limits:

1
# Increase nginx ingress body size
2
kubectl annotate ingress chartmuseum nginx.ingress.kubernetes.io/proxy-body-size=100m
3

4
# For ChartMuseum itself, set MAX_UPLOAD_SIZE
5
kubectl set env deployment/chartmuseum MAX_UPLOAD_SIZE=104857600  # 100MB in bytes

Debugging Push Failures#

Enable verbose logging:

1
# For helm cm-push
2
helm cm-push mychart-0.1.0.tgz myrepo --debug
3

4
# For curl
5
curl -v --data-binary "@mychart-0.1.0.tgz" https://cm.yourdomain.com/api/charts
6

7
# Check ChartMuseum logs
8
kubectl logs deployment/chartmuseum -f

Best Practices and Security Considerations#

1. Access Control#

Use authentication for push operations
Allow anonymous read for internal users
Implement RBAC for different teams
Use separate repositories for dev/staging/prod

2. Chart Versioning#

Follow semantic versioning strictly
Never reuse version numbers
Document breaking changes
Maintain compatibility where possible

3. Storage and Backup#

Enable persistent storage
Regular backups of chart storage
Consider object storage (S3, GCS) for large deployments
Implement retention policies

4. Monitoring#

Monitor ChartMuseum health endpoints
Track storage usage
Alert on push failures
Log all API access

5. Security Scanning#

Scan charts for vulnerabilities
Validate chart templates
Check for hardcoded secrets
Implement admission webhooks for validation

Real-World Example#

Here’s a practical example from the gist:

1
# Package the invinsense-xdr chart
2
helm package ./charts/invinsense-xdr
3

4
# Push to the invinsense repository
5
helm cm-push invinsense-xdr-1.0.0.tgz invinsense

This demonstrates a typical workflow for packaging and publishing a production chart.

Conclusion#

ChartMuseum provides a simple yet powerful solution for hosting Helm charts within your organization. By following this guide, you can set up a robust chart repository with proper security, automation, and management practices. The combination of ChartMuseum with CI/CD automation enables teams to efficiently manage their Kubernetes applications through Helm charts, promoting consistency and reliability across deployments.

Remember to regularly update ChartMuseum and review your security settings to maintain a secure and efficient chart repository infrastructure.