Manage cluster applications

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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 GitLab 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 the upper-right corner, select Create new ({{< icon name="plus" >}}) and New project/repository.
2. Select Create from template.
3. From the list of templates, next to GitLab Cluster Management, select Use template.
4. Enter the project details.
5. Select Create project.
6. 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 main helmfile.yml file.
• The directory with built-in applications.

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 GitLab Self-Managed instance, you must modify the .gitlab-ci.yml file. Specifically, the section that starts with the comment Automatic package upgrades does not work on a GitLab 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, depending on the state of your cluster and Helm releases, Helmfile attempts to install or update apps every time the pipeline runs. If you change this attribute to installed: false, Helmfile tries 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:

• Cert-manager
• GitLab Runner
• Ingress
• Vault

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.