Complete Guide: Setting Up and Publishing Helm Charts to ChartMuseum

Table of contents#

1. Setting Up ChartMuseum#

Install ChartMuseum in Kubernetes#

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#

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

2. Creating a Helm 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

Edit Chart.yaml to set 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"

3. Packaging the Chart#

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

4
# Sign the chart (optional)
5
# First, set up GPG keys if needed
6
gpg --full-generate-key
7

8
# Export keys to format Helm can use
9
gpg --export > ~/.gnupg/pubring.gpg
10
gpg --export-secret-keys > ~/.gnupg/secring.gpg
11

12
# Package with signing
13
helm package ./mychart --sign --key "Your Name <your.email@example.com>"
14

15
# Verify package
16
helm verify mychart-0.1.0.tgz

4. Pushing to ChartMuseum#

Method 1: Using the Helm CM-Push 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

Method 2: Using cURL#

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

5. Managing Charts in ChartMuseum#

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
# List all versions
11
helm search repo myrepo/mychart --versions
12

13
# Delete a chart version
14
curl -X DELETE https://cm.yourdomain.com/api/charts/mychart/0.1.0

6. Automating with CI/CD#

Create a GitHub workflow .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@v2
15

16
      - name: Set up Helm
17
        uses: azure/setup-helm@v1
18

19
      - name: Add Helm Push Plugin
20
        run: helm plugin install https://github.com/chartmuseum/helm-push
21

22
      - name: Add ChartMuseum Repo
23
        run: helm repo add myrepo https://cm.yourdomain.com
24

25
      - name: Package and Push Charts
26
        run: |
27
          for chart in ./charts/*; do
28
            if [ -d "$chart" ]; then
29
              helm package "$chart"
30
              chart_file=$(basename "$chart")-$(grep '^version:' "$chart/Chart.yaml" | awk '{print $2}').tgz
31
              helm cm-push "$chart_file" myrepo --force
32
            fi
33
          done

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

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

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

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

Example Usage#

1
helm package ./charts/invinsense-xdr
2
helm cm-push invinsense-xdr-1.0.0.tgz invinsense

This comprehensive guide covers all aspects of setting up ChartMuseum and managing Helm charts, from basic installation to advanced CI/CD automation. ChartMuseum provides an excellent solution for hosting private Helm charts with a simple API for programmatic chart management.