Cluster management project (deprecated)
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
- Disabled on GitLab Self-Managed in GitLab 15.0.
The cluster management project was deprecated in GitLab 14.5. To manage cluster applications, use the GitLab agent with the Cluster Management Project Template.
On GitLab Self-Managed, 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:
- 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:
- On the left sidebar, at the bottom, select Admin.
- 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
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support