Cluster management project (deprecated)

DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed

Introduced in GitLab 12.5.

Deprecated in GitLab 14.5.

Disabled on self-managed in GitLab 15.0.

WARNING: The cluster management project was deprecated in GitLab 14.5. To manage cluster applications, use the GitLab agent with the Cluster Management Project Template.

FLAG: On self-managed GitLab, by default this feature is not available. To make it available, an administrator can enable the feature flag named certificate_based_clusters.

A project can be designated as the management project for a cluster. A management project can be used to run deployment jobs with Kubernetes cluster-admin privileges.

This can be useful for:

Creating pipelines to install cluster-wide applications into your cluster, see management project template for details.
Any jobs that require cluster-admin privileges.

Permissions

Only the management project receives cluster-admin privileges. All other projects continue to receive namespace scoped edit level privileges.

Management projects are restricted to the following:

For project-level clusters, the management project must be in the same namespace (or descendants) as the cluster's project.
For group-level clusters, the management project must be in the same group (or descendants) as the cluster's group.
For instance-level clusters, there are no such restrictions.

How to create and configure a cluster management project

To use a cluster management project to manage your cluster:

Create a new project to serve as the cluster management project for your cluster.
Associate the cluster with the management project.
Configure your cluster's pipelines.
Set the environment scope.

Associate the cluster management project with the cluster

To associate a cluster management project with your cluster:

Navigate to the appropriate configuration page. For a:
- Project-level cluster, go to your project's Operate > Kubernetes clusters page.
- Group-level cluster, go to your group's Kubernetes page.
- Instance-level cluster:
  1. On the left sidebar, at the bottom, select Admin Area.
  2. Select Kubernetes.
Expand Advanced settings.
From the Cluster management project dropdown list, select the cluster management project you created in the previous step.

Configuring your pipeline

After designating a project as the management project for the cluster, add a .gitlab-ci.yml file in that project. For example:

configure cluster:
  stage: deploy
  script: kubectl get namespaces
  environment:
    name: production

Setting the environment scope

Environment scopes are usable when associating multiple clusters to the same management project.

Each scope can only be used by a single cluster for a management project.

For example, let's say the following Kubernetes clusters are associated to a management project:

Cluster	Environment scope
Development	`*`
Staging	`staging`
Production	`production`

The environments set in the .gitlab-ci.yml file deploy to the Development, Staging, and Production cluster.

stages:
  - deploy

configure development cluster:
  stage: deploy
  script: kubectl get namespaces
  environment:
    name: development

configure staging cluster:
  stage: deploy
  script: kubectl get namespaces
  environment:
    name: staging

configure production cluster:
  stage: deploy
  script: kubectl get namespaces
  environment:
    name: production