Skip to content

GitLab

Cluster Management project template (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.

With a cluster management project you can manage your cluster's deployment and applications through a repository in GitLab.

The Custer Management project template provides you a baseline to get started and flexibility to customize your project to your cluster's needs. For instance, you can:

  • Extend the CI/CD configuration.
  • Configure the built-in cluster applications.
  • Remove the built-in cluster applications you don't need.
  • Add other cluster applications using the same structure as the ones already available.

The template contains the following components:

  • A pre-configured GitLab CI/CD file so that you can configure deployment pipelines.
  • A pre-configured Helmfile so that you can manage cluster applications with Helm v3.
  • An applications directory with a helmfile.yaml configured for each application available in the template.

WARNING: If you used GitLab Managed Apps to manage your cluster from GitLab, see how to migrate from GitLab Managed Apps to the Cluster Management project.

Set up the management project from the Cluster Management project template

To set up your cluster's management project off of the Cluster Management project template:

  1. Create a new project based on the Cluster Management template.
  2. Associate the cluster management project with your cluster.
  3. Use the available components to manage your cluster.

Create a new project based on the Cluster Management template

To get started, create a new project based on the Cluster Management project template to use as a cluster management project.

You can either create the new project from the template or import the project from the URL. Importing the project is useful if you are using a GitLab self-managed instance that may not have the latest version of the template.

To create the new project:

  • From the template: select the GitLab Cluster Management project template.
  • Importing from the URL: use https://gitlab.com/gitlab-org/project-templates/cluster-management.git.

Available components

Use the available components to configure your cluster:

The .gitlab-ci.yml file

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

  • gl-fail-if-helm2-releases-exist {namespace}: It tries to detect whether you have apps deployed through Helm v2 releases for a given namespace. If so, it will fail the pipeline and ask you to manually migrate your Helm v2 releases to Helm v3.
  • gl-ensure-namespace {namespace}: It creates the given namespace if it does not exist and adds the necessary label for the Cilium app network policies to work.
  • gl-adopt-resource-with-helm-v3 {arguments}: Used only internally in the cert-manager's Helmfile to facilitate the GitLab Managed Apps adoption.
  • gl-adopt-crds-with-helm-v3 {arguments}: Used only internally in the cert-manager's Helmfile to facilitate the GitLab Managed Apps adoption.
  • gl-helmfile {arguments}: A thin wrapper that triggers the Helmfile command.

The main helmfile.yml file

This file has a list of paths to other Helmfiles 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.

Furthermore, each app has an applications/{app}/values.yaml file (applicaton/{app}/values.yaml.gotmpl in case of GitLab Runner). This is the place where you can define default values for your app's Helm chart. Some apps already have defaults pre-defined by GitLab.

Built-in applications

The built-in supported applications are: