Skip to content
GitLab

Manage cluster applications (FREE)

  • Introduced in GitLab 12.10 with Helmfile support via Helm v2.
  • Helm v2 support was dropped in GitLab 14.0. Use Helm v3 instead.
  • Migrated to the GitLab agent in GitLab 14.5.

GitLab provides a cluster management project template, which you use to create a project. The project includes cluster applications that integrate with GitLab and extend GitLab functionality. You can use the pattern shown in the project to extend your custom cluster applications.

NOTE: The project template works on GitLab.com without modifications. If you're on a self-managed instance, you must modify the .gitlab-ci.yml file.

Use one project for the agent and your manifests

If you have not yet used the agent to connect your cluster with GitLab:

  1. Create a project from the cluster management project template.
  2. Configure the project for the agent.
  3. In your project's settings, create an environment variable named $KUBE_CONTEXT and set the value to path/to/agent-configuration-project:your-agent-name.
  4. Configure the files as needed.

Use separate projects for the agent and your manifests

If you have already configured the agent and connected a cluster with GitLab:

  1. Create a project from the cluster management project template.
  2. In the project where you configured your agent, grant the agent access to the new project.
  3. In the new project, create an environment variable named $KUBE_CONTEXT and set the value to path/to/agent-configuration-project:your-agent-name.
  4. In the new project, configure the files as needed.

Create a project based on the cluster management project template

To create a project from the cluster management project template:

  1. In GitLab, on the top bar, select Main menu > Projects > View all projects.
  2. On the right of the page, select New project.
  3. Select Create from template.
  4. From the list of templates, next to GitLab Cluster Management, select Use template.
  5. Enter the project details.
  6. Select Create project.
  7. In the new project, configure the files as needed.

Configure the project

After you use the cluster management template to create a project, you can configure:

The .gitlab-ci.yml file

The .gitlab-ci.yml file:

  • Ensures you are on Helm version 3.
  • Deploys the enabled applications from the project.

You can edit and extend the pipeline definitions.

The base image used in the pipeline is built by the cluster-applications project. This image contains a set of Bash utility scripts to support Helm v3 releases.

If you are on a self-managed instance of GitLab, you must modify the .gitlab-ci.yml file. Specifically, the section that starts with the comment Automatic package upgrades does not work on a self-managed instance, because the include refers to a GitLab.com project. If you remove everything below this comment, the pipeline succeeds.

The main helmfile.yml file

The template contains a Helmfile you can use to manage cluster applications with Helm v3.

This file has a list of paths to other Helm files for each app. They're all commented out by default, so you must uncomment the paths for the apps that you would like to use in your cluster.

By default, each helmfile.yaml in these sub-paths has the attribute installed: true. This means that every time the pipeline runs, Helmfile tries to either install or update your apps according to the current state of your cluster and Helm releases. If you change this attribute to installed: false, Helmfile tries try to uninstall this app from your cluster. Read more about how Helmfile works.

Built-in applications

The template contains an applications directory with a helmfile.yaml configured for each application in the template.

The built-in supported applications are:

Each application has an applications/{app}/values.yaml file. For GitLab Runner, the file is applications/{app}/values.yaml.gotmpl.

In this file, you can define default values for your app's Helm chart. Some apps already have defaults defined.