The Chart Repository Guide

    The official chart repository is maintained by theHelm Charts, and we welcomeparticipation. But Helm also makes it easy to create and run your own chartrepository. This guide explains how to do so.

    • Go through the Guide
    • Read through the Charts document

    A chart repository is an HTTP server that houses an file andoptionally some packaged charts. When you’re ready to share your charts, thepreferred way to do so is by uploading them to a chart repository.

    Note: For Helm 2.0.0, chart repositories do not have any intrinsicauthentication. There is an in GitHub.

    Because a chart repository can be any HTTP server that can serve YAML and tarfiles and can answer GET requests, you have a plethora of options when it comesdown to hosting your own chart repository. For example, you can use a GoogleCloud Storage (GCS) bucket, Amazon S3 bucket, Github Pages, or even create yourown web server.

    A chart repository consists of packaged charts and a special file calledindex.yaml which contains an index of all of the charts in the repository.Frequently, the charts that index.yaml describes are also hosted on the sameserver, as are the provenance files.

    For example, the layout of the repository mightlook like this:

    In this case, the index file would contain information about one chart, the Alpinechart, and provide the download URL https://example.com/charts/alpine-0.1.2.tgzfor that chart.

    It is not required that a chart package be located on the same server as theindex.yaml file. However, doing so is often the easiest.

    The index file

    The index file is a yaml file called index.yaml. Itcontains some metadata about the package, including the contents of achart’s Chart.yaml file. A valid chart repository must have an index file. Theindex file contains information about each chart in the chart repository. Thehelm repo index command will generate an index file based on a given localdirectory that contains packaged charts.

    This is an example of an index file:

    1. apiVersion: v1
    2. entries:
    3.   alpine:
    4.     - created: 2016-10-06T16:23:20.499814565-06:00
    5.       description: Deploy a basic Alpine Linux pod
    6.       digest: 99c76e403d752c84ead610644d4b1c2f2b453a74b921f422b9dcb8a7c8b559cd
    7.       home: https://k8s.io/helm
    8.       sources:
    9.       - https://github.com/helm/helm
    10.       urls:
    11.       - https://technosophos.github.io/tscharts/alpine-0.2.0.tgz
    12.       version: 0.2.0
    13.     - created: 2016-10-06T16:23:20.499543808-06:00
    14.       description: Deploy a basic Alpine Linux pod
    15.       digest: 515c58e5f79d8b2913a10cb400ebb6fa9c77fe813287afbacf1a0b897cd78727
    16.       home: https://k8s.io/helm
    17.       name: alpine
    18.       sources:
    19.       - https://github.com/helm/helm
    20.       urls:
    22.       version: 0.1.0
    23.   nginx:
    24.     - created: 2016-10-06T16:23:20.499543808-06:00
    25.       description: Create a basic nginx HTTP server
    26.       digest: aaff4545f79d8b2913a10cb400ebb6fa9c77fe813287afbacf1a0b897cdffffff
    27.       home: https://k8s.io/helm
    28.       name: nginx
    29.       sources:
    30.       - https://github.com/helm/charts
    31.       urls:
    32.       version: 1.1.0
    33. generated: 2016-10-06T16:23:20.499029981-06:00

    A generated index and packages can be served from a basic webserver. You can testthings out locally with the helm serve command, which starts a local server.

    1. $ helm serve --repo-path ./charts
    2. Regenerating index. This may take a moment.
    3. Now serving you on 127.0.0.1:8879

    The above starts a local webserver, serving the charts it finds in ./charts. Theserve command will automatically generate an index.yaml file for you duringstartup.

    This part shows several ways to serve a chart repository.

    ChartMuseum

    The Helm project provides an open-source Helm repository server called that you can host yourself.

    ChartMuseum supports multiple cloud storage backends. Configure it to point to the directory or bucket containing your chart packages, and the index.yaml file will be generated dynamically.

    It can be deployed easily as a Helm chart:

    and also as a :

    1. docker run --rm -it \
    2.   -p 8080:8080 \
    3.   -v $(pwd)/charts:/charts \
    4.   -e DEBUG=true \
    5.   -e STORAGE=local \
    6.   -e STORAGE_LOCAL_ROOTDIR=/charts \
    7.   chartmuseum/chartmuseum

    You can then add the repo to your local repository list:

    1. helm repo add chartmuseum http://localhost:8080

    The first step is to create your GCS bucket. We’ll call oursfantastic-charts.

    Next, make your bucket public by editing the bucket permissions.

    Edit Permissions

    Insert this line item to make your bucket public:

    Congratulations, now you have an empty GCS bucket ready to serve charts!

    You may upload your chart repository using the Google Cloud Storage command linetool, or using the GCS web UI. This is the technique the official KubernetesCharts repository hosts its charts, so you may want to take apeek at that project if you get stuck.

    Note: A public GCS bucket can be accessed via simple HTTPS at this address.

    JFrog Artifactory

    You can also set up chart repositories using JFrog Artifactory.Read more about chart repositories with JFrog Artifactory

    ProGet

    Helm chart repositories are supported by ProGet. For more information, visit the on the Inedo website.

    In a similar way you can create charts repository using GitHub Pages.

    GitHub allows you to serve static web pages in two different ways:

    • By configuring a project to serve the contents of its directory
    • By configuring a project to serve a particular branchWe’ll take the second approach, though the first is just as easy.

    The first step will be to create your gh-pages branch. You can do thatlocally as.

    Or via web browser using Branch button on your Github repository:

    Create Github Pages branch

    Next, you’ll want to make sure your gh-pages branch is set as Github Pages,click on your repo Settings and scroll down to Github pages section andset as per below:

    You can use a custom domain there if you wish so.

    And check that Enforce HTTPS is ticked, so the HTTPS will be used whencharts are served.

    In such setup you can use master branch to store your charts code, andgh-pages branch as charts repository, e.g.:https://USERNAME.github.io/REPONAME. The demonstration repository is accessible at https://technosophos.github.io/tscharts/.

    Ordinary web servers

    To configure an ordinary web server to serve Helm charts, you merely need to dothe following:

    • Put your index and charts in a directory that the server can serve
    • Make sure the index.yaml file can be accessed with no authentication requirement
    • Make sure yaml files are served with the correct content type (text/yaml ortext/x-yaml)For example, if you want to serve your charts out of $WEBROOT/charts, make surethere is a charts/ directory in your web root, and put the index file andcharts inside of that folder.

    Now that you have a chart repository, the last part of this guide explains howto maintain charts in that repository.

    Store charts in your chart repository

    Now that you have a chart repository, let’s upload a chart and an index file tothe repository. Charts in a chart repository must be packaged(helm package chart-name/) and versioned correctly (following guidelines).

    These next steps compose an example workflow, but you are welcome to usewhatever workflow you fancy for storing and updating charts in your chartrepository.

    Once you have a packaged chart ready, create a new directory, and move yourpackaged chart to that directory.

    1. $ helm package docs/examples/alpine/
    2. $ mkdir fantastic-charts
    3. $ mv alpine-0.1.0.tgz fantastic-charts/
    4. $ helm repo index fantastic-charts --url https://fantastic-charts.storage.googleapis.com

    The last command takes the path of the local directory that you just created andthe URL of your remote chart repository and composes an index.yaml file inside thegiven directory path.

    Now you can upload the chart and the index file to your chart repository usinga sync tool or manually. If you’re using Google Cloud Storage, check out thisexample workflow using the gsutil client. ForGitHub, you can simply put the charts in the appropriate destination branch.

    Each time you want to add a new chart to your repository, you must regeneratethe index. The helm repo index command will completely rebuild the index.yamlfile from scratch, including only the charts that it finds locally.

    However, you can use the —merge flag to incrementally add new charts to anexisting index.yaml file (a great option when working with a remote repositorylike GCS). Run helm repo index —help to learn more,

    Make sure that you upload both the revised index.yaml file and the chart. Andif you generated a provenance file, upload that too.

    Share your charts with others

    When you’re ready to share your charts, simply let someone know what the URL ofyour repository is.

    From there, they will add the repository to their helm client via the helmrepo add [NAME] [URL] command with any name they would like to use toreference the repository.

    1. $ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com
    2. $ helm repo list

    If the charts are backed by HTTP basic authentication, you can also supply theusername and password here:

    Note: A repository will not be added if it does not contain a validindex.yaml.

    After that, your users will be able to search through your charts. After you’ve updatedthe repository, they can use the helm repo update command to get the latestchart information.