2020-05-12 03:09:31 +00:00
---
stage: Configure
group: Configure
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-12 03:09:31 +00:00
---
2021-10-27 21:11:33 +00:00
# Cluster management project (DEPRECATED) **(FREE)**
2019-10-14 12:06:14 +00:00
2021-10-27 21:11:33 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5.
> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
2022-05-14 03:09:09 +00:00
> - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/353410) in GitLab 15.0.
2021-10-27 21:11:33 +00:00
WARNING:
2021-11-09 18:13:13 +00:00
The cluster management project was [deprecated ](https://gitlab.com/groups/gitlab-org/configure/-/epics/8 ) in GitLab 14.5.
2022-02-22 00:14:20 +00:00
To manage cluster applications, use the [GitLab agent ](agent/index.md )
2021-11-08 18:09:52 +00:00
with the [Cluster Management Project Template ](management_project_template.md ).
2022-05-14 03:09:09 +00:00
FLAG:
On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag ](../../administration/feature_flags.md ) named `certificate_based_clusters` .
2019-10-14 12:06:14 +00:00
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` ](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles )
privileges.
This can be useful for:
2021-06-10 21:10:02 +00:00
- Creating pipelines to install cluster-wide applications into your cluster, see [management project template ](management_project_template.md ) for details.
2019-10-14 12:06:14 +00:00
- Any jobs that require `cluster-admin` privileges.
## Permissions
2020-11-19 00:09:41 +00:00
Only the management project receives `cluster-admin` privileges. All
2021-06-18 15:10:16 +00:00
other projects continue to receive [namespace scoped `edit` level privileges ](../project/clusters/cluster_access.md#rbac-cluster-resources ).
2019-10-14 12:06:14 +00:00
2019-10-24 12:06:03 +00:00
Management projects are restricted to the following:
2020-02-07 03:08:59 +00:00
- For project-level clusters, the management project must be in the same
2019-10-24 12:06:03 +00:00
namespace (or descendants) as the cluster's project.
2020-02-07 03:08:59 +00:00
- For group-level clusters, the management project must be in the same
2020-04-08 06:09:54 +00:00
group (or descendants) as the cluster's group.
2019-10-24 12:06:03 +00:00
- For instance-level clusters, there are no such restrictions.
2021-09-15 12:11:13 +00:00
## How to create and configure a cluster management project
2019-10-14 12:06:14 +00:00
2021-09-15 12:11:13 +00:00
To use a cluster management project to manage your cluster:
2019-11-14 03:06:25 +00:00
2021-09-15 12:11:13 +00:00
1. Create a new project to serve as the cluster management project
2021-11-08 18:09:52 +00:00
for your cluster.
2021-09-15 12:11:13 +00:00
1. [Associate the cluster with the management project ](#associate-the-cluster-management-project-with-the-cluster ).
1. [Configure your cluster's pipelines ](#configuring-your-pipeline ).
1. [Set the environment scope ](#setting-the-environment-scope ).
2019-11-14 03:06:25 +00:00
2021-09-15 12:11:13 +00:00
### Associate the cluster management project with the cluster
2019-10-14 12:06:14 +00:00
2021-09-15 12:11:13 +00:00
To associate a cluster management project with your cluster:
2019-11-14 03:06:25 +00:00
1. Navigate to the appropriate configuration page. For a:
2021-06-18 18:10:13 +00:00
- [Project-level cluster ](../project/clusters/index.md ), go to your project's
2021-06-16 00:10:15 +00:00
**Infrastructure > Kubernetes clusters** page.
2021-06-18 18:10:13 +00:00
- [Group-level cluster ](../group/clusters/index.md ), go to your group's **Kubernetes**
2020-03-18 06:09:38 +00:00
page.
2021-08-26 09:11:15 +00:00
- [Instance-level cluster ](../instance/clusters/index.md ), on the top bar, select **Menu > Admin > Kubernetes** .
2021-09-15 12:11:13 +00:00
1. Expand **Advanced settings** .
1. From the **Cluster management project** dropdown, select the cluster management project
you created in the previous step.
2019-10-14 12:06:14 +00:00
### Configuring your pipeline
After designating a project as the management project for the cluster,
2021-06-28 21:10:13 +00:00
write a [`.gitlab-ci.yml` ](../../ci/yaml/index.md ) in that project. For example:
2019-10-14 12:06:14 +00:00
```yaml
configure cluster:
stage: deploy
script: kubectl get namespaces
environment:
name: production
```
2020-08-13 00:10:06 +00:00
### Setting the environment scope
2019-10-14 12:06:14 +00:00
2022-08-08 03:09:21 +00:00
[Environment scopes ](../project/clusters/multiple_kubernetes_clusters.md#setting-the-environment-scope )
2019-10-14 12:06:14 +00:00
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` |
2019-11-18 06:06:20 +00:00
The following environments set in
2021-06-28 21:10:13 +00:00
[`.gitlab-ci.yml` ](../../ci/yaml/index.md ) deploy to the
2019-10-14 12:06:14 +00:00
Development, Staging, and Production cluster respectively.
```yaml
stages:
2020-07-03 09:08:53 +00:00
- deploy
2019-10-14 12:06:14 +00:00
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
```