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
Things that have been said in Helm land
"Finally!!"
"ChartMuseum is awesome"
"This is awesome!"
"Oh yes!!!! I’ve been waiting for this for so long. Makes life much easier, especially for the index.yaml creation!"
"I was thinking about writing one of these up myself. This is perfect! thanks!"
"I am jumping for joy over ChartMuseum, a full-fledged Helm repository server with upload!"
"This is really cool ... We currently have a process that generates the index file and then uploads, so this is nice"
"Really a good idea ... really really great, thanks again. I can use nginx to hold the repos and the museum to add/delete the chart. That's a whole life cycle management of chart with the current helm"
"thanks for building the museum!"
API
Helm Chart Repository
GET /index.yaml
- retrieved when you runhelm repo add chartmuseum http://localhost:8080/
GET /charts/mychart-0.1.0.tgz
- retrieved when you runhelm install chartmuseum/mychart
GET /charts/mychart-0.1.0.tgz.prov
- retrieved when you runhelm install
with the--verify
flag
Chart Manipulation
POST /api/charts
- upload a new chart versionPOST /api/prov
- upload a new provenance fileDELETE /api/charts/<name>/<version>
- delete a chart version (and corresponding provenance file)GET /api/charts
- list all chartsGET /api/charts/<name>
- list all versions of a chartGET /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
Both files can also be uploaded at once (or one at a time) on the api/charts
route using the multipart/form-data
format:
curl -F "chart=@mychart-0.1.0.tgz" -F "prov=@mychart-0.1.0.tgz.prov" http://localhost:8080/api/charts
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.2.1
).
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"
Basic Auth
If both of the following options are provided, basic http authentication will protect all routes:
--basic-auth-user=<user>
- username for basic http authentication--basic-auth-pass=<pass>
- password for basic http authentication
HTTPS
If both of the following options are provided, the server will listen and serve HTTPS:
--tls-cert=<crt>
- path to tls certificate chain file--tls-key=<key>
- path to tls key file
Just generating index.yaml
You can specify the --gen-index
option if you only wish to use ChartMuseum to generate your index.yaml file.
The contents of index.yaml will be printed to stdout and the program will exit. This is useful if you are satisfied with your current Helm CI/CD process and/or don't want to monitor another webservice.
Other CLI options
--log-json
- output structured logs as json--disable-api
- disable all routes prefixed with /api--chart-url=<url>
- absolute url for .tgzs in index.yaml
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"
Helm Chart
There is a Helm chart for ChartMuseum itself which can be found in the official Kubernetes Charts repository.
You can also view it on KubeApps.
To install:
helm repo add incubator https://kubernetes-charts-incubator.storage.googleapis.com
helm install incubator/chartmuseum
Please note that for now, this should only be used for testing purposes. An emptyDir volume is currently being used for storage, which means your .tgzs will disappear when the pod is removed. If you can help get this to work with persistent storage or any of the cloud storage options, please submit a PR to kubernetes/charts. Thanks!
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
.
The --gen-index
CLI option (described above) can be used to generate and print index.yaml to stdout.
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"