How to host helm charts with gitlab package registry

Helm helps you manage Kubernetes applications. Helm Charts help you define, install, and upgrade even the most complex Kubernetes application. Helm charts are a collection of Kubernetes YAML manifests distributed as a single package. They make it faster and easier to deploy complex applications in your cluster. Using GitLab as a ledger allows your team to store charts with your code in an organization-managed repository.

Also check:

Using the Helm GitLab repository

Make sure your GitLab instance has been updated to version 14.1. If you are using the GitLab.com hosted deployment, you will already have everything you need.

Switch over to your GitLab instance. Either create a new project or find an existing one. Using the left sidebar, navigate to Packages & Registries > Package Registry within your project. If you don’t see these menus, head to Settings > General, expand the “Visibility, project features, permissions” heading, and enable the “Packages” toggle.

Creating hem chart

To create a helm chart, use the helm create command.

1
2
➜ helm create nginx
Creating nginx

Helm create a directory with the name you supplied. The directory contains the templates and chart definition. Inspect using this command:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
➜ tree nginx
nginx
├── Chart.yaml
├── charts
├── templates
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── tests
│       └── test-connection.yaml
└── values.yaml

4 directories, 10 files

Helm creates a starter chart directory along with the common files and directories used in a chart with NGINX as an example. We can install this into our Kubernetes cluster:

1
helm install nginx .

Package for distribution

To distribute helm chart, it has to be hosted in a repo. You can build the helm chart into a compressed file for ease of distribution using this command:

1
2
3
➜ helm package nginx

Successfully packaged chart and saved it to: /tmp/helm/nginx-0.1.0.tgz

The command creates a new tar.gz archive ready to upload. Before doing so, you can inspect the archive with the tar command to verify its content.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
➜ tar ztf nginx-0.1.0.tgz

nginx/Chart.yaml
nginx/values.yaml
nginx/templates/NOTES.txt
nginx/templates/_helpers.tpl
nginx/templates/deployment.yaml
nginx/templates/hpa.yaml
nginx/templates/ingress.yaml
nginx/templates/service.yaml
nginx/templates/serviceaccount.yaml
nginx/templates/tests/test-connection.yaml
nginx/.helmignore

Publish a package in Gitlab Package registry

For this, you need a username and an access token. To get it, head over to user settings in gitlab then access tokens. Create a new access token with api access. You can generate a new token by clicking your profile icon in the top-right of GitLab’s interface. Select “Preferences” from the menu, then “Access Tokens” from the left sidebar. Add a new access token with the api scope. The write_repository scope might look correct but won’t actually work; it only facilitates access using Git over HTTP, whereas Helm requires API integration. Checkout more information here.

Once built, a chart can be uploaded to the desired channel with curl or helm cm-push:

With curl:

1
2
3
4
curl --request POST \
    --form 'chart=@mychart-0.1.0.tgz' \
    --user  <username>:<access_token> \
    https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/api/<channel>/charts

<username>: the GitLab username or the deploy token username.
<access_token>: the personal access token or the deploy token.
<project_id>: the project ID (like 42) or the URL-encoded path of the project (like group/project).
<channel>: the name of the channel (like stable).

This is the output on my server

1
2
3
4
5
6
➜ curl --request POST \
    --form 'chart=@nginx-0.1.0.tgz' \
    --user api-token:glpat-xxxxxxxxxxxxx \
    https://gitlab.com/api/v4/projects/34000009/packages/helm/api/helm/charts

{"message":"201 Created"}

With the `helm cm-push` plugin

For this you will need the plugin installed. Use this command:

1
helm plugin install https://github.com/chartmuseum/helm-push

Then you need to register it with your Helm client to begin with. Use this command:

1
2
3
helm repo add --username  <username> --password  <access_token> citizix \
    https://gitlab.example.com/api/v4/projects/<project_id>/packages/helm/<channel>
helm cm-push mychart-0.1.0.tgz citizix

<username>: the GitLab username or the deploy token username.
<access_token>: the personal access token or the deploy token.
<project_id>: the project ID (like 42).
<channel>: the name of the channel (like stable).

This is it in my machine

1
2
3
➜ helm repo add --username api-token --password glpat-xxxxx citizix https://gitlab.com/api/v4/projects/34000000/packages/helm/stable

"citizix" has been added to your repositories

Then push

1
2
3
4
➜ helm cm-push nginx-0.1.0.tgz citizix

Pushing nginx-0.1.0.tgz to citizix...
Done.

Confirm

1
2
3
➜ helm search repo citizix
NAME       	CHART VERSION	APP VERSION	DESCRIPTION
citizix/nginx	0.1.0        	1.16.0     	A Helm chart for Kubernetes

Using Charts in the Repository

With the chart in your repository, you can deploy it into your Kubernetes cluster. helm install commands should work straightaway:

1
2
3
4
5
# load the contents of repositories
helm repo update

# install the chart
helm install citizix/nginx

This will start a new chart deployment into your active cluster. Use the --kubeconfig and --namespace Helm flags if necessary to select an appropriate Kubernetes configuration file and specify the namespace to deploy into.

Accessing GitLab’s Repository in a CI Pipeline

As with its other package formats, GitLab’s Helm repository benefits from built-in integration with the software’s CI/CD system. Your pipelines will receive preset environment variables which simplify the chart publication process. You don’t need to set any custom CI variables to configure authentication.

Here’s an example pipeline which creates a chart and publishes it to your repository:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
stages:
  - helm-publish

helm-publish:
  stage: helm-publish
  image:
    name: alpine/helm:latest
    entrypoint: [""]
  script:
    - helm repo add --username $CI_REGISTRY_USER --password $CI_REGISTRY_PASSWORD my-repo $CI_REGISTRY
    - helm package my-chart
    - helm push my-chart.tgz my-repo

The $CI_REGISTRY variables are configured to let you push new packages into the registry.