Let’s set up your own Helm chart repo and start publishing Helm charts!

6 min readApr 8, 2023

Overview

In this post, I’ll share a very simple way to create and publish a helm chart.

What is Helm chart?

Helm is a tool to make it easy to manage Kubernetes yaml files of an application, such as installation, upgrade, versioning, sharing, and more and more.

A Helm chart is a unit that bundles Kubernetes yaml files that you want to manage together, simply you can think of an application.

If you have an application (or sometimes Kubernetes operator) to run on Kubernetes, you’d have several Kubernetes manifest yaml files e.g. deployment.yaml, configmap.yaml, service.yaml, ... Those files are managed together in a Helm chart with versions.

When you want to install a chart, which means deploying the managed application to a Kubernetes cluster, a Chart version is specified and a release is created.

A release can be thought of as a specific version of an application installed by Helm. If you uninstall a release, the deployed application, more specifically, the Kubernetes objects created by a Helm chart will be deleted from the Kubernetes cluster.

If you want to get familiar with Helm, you can go through the official quickstart.

Create a Helm chart

You can install helm cli with brew install helm if you’re using MacOS. For other OS, you can check installation.

It’s pretty simple to create a sample helm chart.

First, create a chart with the following command:

helm create helm-example

The command will generate the following files

tree
.
├── Chart.yaml
├── charts
├── templates
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── tests
│       └── test-connection.yaml
└── values.yaml

3 directories, 10 files

Roughly speaking, a Helm chart consists of two parts:

templates: a group of Kubernetes yaml files that is written in the Helm template syntax. e.g. {{ Values.someValue }} this kind of values are passed from values.yaml
values.yaml: variables that you can interpolate in templates.

For more details, please read https://helm.sh/docs/chart_template_guide/getting_started/

You can start with yaml files without any values for simplicity.

How to publish a Helm chart

After creating a Helm chart, it’s nice to have a place to publish and share.

The place to publish and share is called repository. I’ll share one of the simplest ways to set up your own Helm chart repository with GitHub pages.

A Helm chart repository consists of two types of files:

index.yaml: contains information about each chart in the repository
each of packaged chart file. e.g. your-app-0.1.0.tgz

1. Create GitHub repo helm-charts

I’m using my own GitHub repository https://github.com/nakamasato/helm-charts. You can create your own under your GitHub account.

This repository can store all of your Helm charts to publish and share.

2. Setup GitHub Pages

To set up GitHub Pages, go to the settings page from https://github.com/<your github account>/helm-charts/settings/pages, and set Branch to gh-pages. If you don’t have gh-pages branch yet, you might not be able to select it. In that case, you need to push the same content as main branch to gh-pages branch and try again.

After this settings, GitHub pages will be created on gh-pages, which serves as an HTTP server.

You can also find related contents in the official doc: https://helm.sh/docs/topics/chart_repository/#github-pages-example

3. Configure GitHub Actions

There’s a very useful GitHub Actions that automate management of index.yaml that is necessary for a Helm repository.

helm-chart-releaser helps you keep index.yaml based on the charts in the repository.

So all you need to do after using this GitHub Actions is just push your Helm chart files under charts directory. Then GitHub Actions make packaged Helm chart, release, and update index.yaml on gh-pages branch, which is the branch served by GitHub Pages that we set up in the above step.

name: release

on:
  push:
    branches:
      - main

jobs:
  release:
    # depending on default permission settings for your org (contents being read-only or read-write for workloads), you will have to add permissions
    # see: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token
    permissions:
      contents: write
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Configure Git
        run: |
          git config user.name "$GITHUB_ACTOR"
          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
      - name: Install Helm
        uses: azure/setup-helm@v3

      - name: Run chart-releaser
        uses: helm/chart-releaser-action@v1.5.0
        env:
          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

This is the yaml file that you need to include in the repository (ref: https://github.com/nakamasato/helm-charts/blob/main/.github/workflows/release.yaml)

3. Push your Helm chart source code to the repo.

You can push your own helm chart, helm-example in this case here, to the main branch.

The the GitHub Actions automatically creates a new release with packaged Helm chart!

The index.yaml is also created/updated by the workflow on gh-pages branch.

4. Use the created chart

In order to install charts in a repo, you need to register the target repo to helm cli.

If you have never added any repo, you’ll see the following result.

helm repo list
Error: no repositories to show

Now let’s add the created repo with the command helm repo add <give a name to repo> <repository url>. If you try with my repostiory, you can run the following command:

helm repo add nakamasato https://nakamasato.github.io/helm-charts

Then you’ll see the registered repo

helm repo list
NAME       URL
nakamasato https://nakamasato.github.io/helm-charts

Now you can search for a Helm chart in the repo:

helm search repo nakamasato
NAME                      CHART VERSION APP VERSION DESCRIPTION
nakamasato/helm-example   0.1.0         v0.0.1      Simple API application.
nakamasato/mysql-operator v0.2.1        v0.2.1      A Helm chart for Kubernetes

You can install helm-example chart with the following command:

helm install helm-example nakamasato/helm-example

You’ll see something like this

NAME: helm-example
LAST DEPLOYED: Sat Apr  8 21:00:59 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=helm-example,app.kubernetes.io/instance=helm-example" -o jsonpath="{.items[0].metadata.name}")
  export CONTAINER_PORT=$(kubectl get pod --namespace default $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
  echo "Visit http://127.0.0.1:8080 to use your application"
  kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT

You can confirm the installed release with helm list

helm list
NAME         NAMESPACE REVISION UPDATED                              STATUS   CHART              APP VERSION
helm-example default   1        2023-04-08 21:00:59.700476 +0900 JST deployed helm-example-0.1.0 v0.0.1

You can uninstall with helm uninstall helm-example

helm uninstall helm-example
release "helm-example" uninstalled

That’s it! So easy to set up a Helm chart repository and use it, isn’t it?

Summary

Helm is a powerful tool to manage Kubernetes manifests yaml file. This posts shared a very simple and quick way to set up your own Helm chart repository with GitHub pages and GitHub Actions, how to publish your own Helm chart, how to register your repo to helm cli and, how to install the Helm chart.

I hope this quick setup of a Helm chart repository will motivate you to start publish your own Helm charts!