GitLab 14.1 added Helm charts to the software’s growing list of supported package repository formats. You can now store and share your charts using your GitLab projects, without a separate Helm registry.
Helm charts are a collection of Kubernetes YAML manifests distributed as a single package. They make it quicker and easier to deploy complex applications into your cluster. Using GitLab as a registry lets your team store charts alongside your code in an organization-managed repository.
Using the GitLab Helm Repository
Make sure your GitLab instance has been updated to version 14.1. If you’re using the hosted GitLab.com deployment, you’ll already have everything you need.
Prepare a simple Helm chart to push to your repository. Running
helm create example will produce a new boilerplate chart called
example if you’ve not got one available. The generated chart will be ready to push straight up to GitLab, without any modification.
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.
Adding the Repository to Helm
Now you’re ready to start using your package repository. You need to register it with your Helm client to begin with.
helm repo add \ --username <username> \ --password <token> \ example-repo \ https://gitlab.example.com/api/v4/projects/<project>/packages/helm/stable
The local repository will be named
<username> with your GitLab username. The value of
<token> should be a personal access token that’s got permission to push packages.
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.
<project> in your repository URL with the ID of the GitLab project you want to push to. You can find this on its homepage, underneath its name.
Pushing to the Repository
Once the repository’s been added, you can push any directory with a valid Helm chart up to your GitLab instance. It’s usually easiest to install the
helm-push plugin which adds a native
helm push command.
Package your chart if you haven’t already:
helm package example-chart
This will create a gzipped tar archive,
example-chart.tgz, containing your chart.
helm plugin install https://github.com/chartmuseum/helm-push.git
Finally, use the plugin to push your chart to your GitLab repository:
helm push example-chart.tgz example-repo
Back in the GitLab web interface, navigate to your project’s Packages & Registries > Package Registry screen. You should see your chart show up.
Click the chart’s name to view its details. This screen lets you track the chart’s history, download package files, and view older releases. You can delete the chart with the “Delete” button situated in the top-right.
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:
# load the contents of repositories helm repo update # install the chart helm install example-repo/example-chart
This will start a new chart deployment into your active cluster. Use the
--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:
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
$CI_REGISTRY variables are configured to let you push new packages into the registry. You can reuse them when authenticating to GitLab’s other repositories, such as npm, Composer, NuGet, and Maven.
GitLab now has an integrated Helm chart repository that lets you store your Kubernetes manifests alongside your code. Anyone with read access to the project’s repository will be able to add it to their Helm client and deploy charts into Kubernetes clusters.
When a new chart version is published, run
helm repo update and then use
helm upgrade to move deployed installations to the new release. You can manage chart versions from within GitLab and delete old releases which are wasting disk space.