Cluster management project (deprecated)

{{< details >}}

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

{{< /details >}}

{{< history >}}

• Disabled on GitLab Self-Managed in GitLab 15.0.

{{< /history >}}

[!flag] This feature is not available by default on GitLab Self-Managed. 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.

[!warning] The cluster management project was deprecated in GitLab 14.5. To manage cluster applications, use the GitLab agent for Kubernetes with the Cluster Management Project Template.

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:

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

Associate the cluster management project with the cluster

Prerequisites:

• Administrator access to associate an instance cluster.

To associate a cluster management project with your cluster:

1. Go 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. In the upper-right corner, select Admin.
     2. Select Kubernetes.
2. Expand Advanced settings.
3. 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, the following Kubernetes clusters are associated to a management project:

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