chartmuseum

README

ChartMuseum

_{"Preserve your precious artifacts... in the cloud!"}

ChartMuseum is an open-source Helm Chart Repository written in Go (Golang), with support for cloud storage backends, including Google Cloud Storage and Amazon S3.

Works as a valid Helm Chart Repository, and also provides an API for uploading new chart packages to storage etc.

Powered by some great Go technology:

• Kubernetes Helm - for working with charts, generating repository index
• Gin Web Framework - for HTTP routing
• cli - for command line option parsing
• zap - for logging

API

Helm Chart Repository

• GET /index.yaml - retrieved when you run helm repo add chartmuseum http://localhost:8080/
• GET /charts/mychart-0.1.0.tgz - retrieved when you run helm install chartmuseum/mychart
• GET /charts/mychart-0.1.0.tgz.prov - retrieved when you run helm install with the --verify flag

Chart Manipulation

• POST /api/charts - upload a new chart version
• POST /api/prov - upload a new provenance file
• DELETE /api/charts/<name>/<version> - delete a chart version (and corresponding provenance file)
• GET /api/charts - list all charts
• GET /api/charts/<name> - list all versions of a chart
• GET /api/charts/<name>/<version> - describe a chart version

Uploading a Chart Package

_{Follow "How to Run" section below to get ChartMuseum up and running at http://localhost:8080}

First create mychart-0.1.0.tgz using the Helm CLI:

cd mychart/
helm package .

Upload mychart-0.1.0.tgz:

curl --data-binary "@mychart-0.1.0.tgz" http://localhost:8080/api/charts

If you've signed your package and generated a provenance file, upload it with:

curl --data-binary "@mychart-0.1.0.tgz.prov" http://localhost:8080/api/prov

Installing Charts into Kubernetes

Add the URL to your ChartMuseum installation to the local repository list:

helm repo add chartmuseum http://localhost:8080

Search for charts:

helm search chartmuseum/

Install chart:

helm install chartmuseum/mychart

How to Run

CLI

Installation

Install the binary:

# on Linux
curl -LO https://s3.amazonaws.com/chartmuseum/release/latest/bin/linux/amd64/chartmuseum

# on macOS
curl -LO https://s3.amazonaws.com/chartmuseum/release/latest/bin/darwin/amd64/chartmuseum

chmod +x ./chartmuseum
mv ./chartmuseum /usr/local/bin

Using latest in URLs above will get the latest binary (built from master branch).

Replace latest with $(curl -s https://s3.amazonaws.com/chartmuseum/release/stable.txt) to automatically determine the latest stable release (e.g. v0.1.0).

Show all CLI options with chartmuseum --help and determine version with chartmuseum --version

Using with Amazon S3

Make sure your environment is properly setup to access my-s3-bucket

chartmuseum --debug --port=8080 \
  --storage="amazon" \
  --storage-amazon-bucket="my-s3-bucket" \
  --storage-amazon-prefix="" \
  --storage-amazon-region="us-east-1"

Using with Google Cloud Storage

Make sure your environment is properly setup to access my-gcs-bucket

chartmuseum --debug --port=8080 \
  --storage="google" \
  --storage-google-bucket="my-gcs-bucket" \
  --storage-google-prefix=""

Using with local filesystem storage

Make sure you have read-write access to ./chartstorage (will create if doesn't exist)

chartmuseum --debug --port=8080 \
  --storage="local" \
  --storage-local-rootdir="./chartstorage"

Docker Image

Available via Docker Hub.

Example usage (S3):

docker run --rm -it \
  -p 8080:8080 \
  -v ~/.aws:/root/.aws:ro \
  chartmuseum/chartmuseum:latest \
  --debug --port=8080 \
  --storage="amazon" \
  --storage-amazon-bucket="my-s3-bucket" \
  --storage-amazon-prefix="" \
  --storage-amazon-region="us-east-1"

Notes on index.yaml

The repository index (index.yaml) is dynamically generated based on packages found in storage. If you store your own version of index.yaml, it will be completely ignored.

GET /index.yaml occurs when you run helm repo add chartmuseum http://localhost:8080/ or helm repo update.

If you manually add/remove a .tgz package from storage, it will be immediately reflected in GET /index.yaml.

You are no longer required to maintain your own version of index.yaml using helm repo index --merge.

Mirroring the official Kubernetes repositories

Please see scripts/mirror_k8s_repos.sh for an example of how to download all .tgz packages from the official Kubernetes repositories (both stable and incubator).

You can then use ChartMuseum to serve up an internal mirror:

scripts/mirror_k8s_repos.sh
chartmuseum --debug --port=8080 --storage="local" --storage-local-rootdir="./mirror"