Group-level Kubernetes clusters (certificate-based) (deprecated)
Offering: GitLab.com, Self-managed, GitLab Dedicated
- Introduced in GitLab 11.6.
- Deprecated in GitLab 14.5.
Similar to project-level and instance-level Kubernetes clusters, group-level Kubernetes clusters allow you to connect a Kubernetes cluster to your group, enabling you to use the same cluster across multiple projects.
To view your group-level Kubernetes clusters:
- On the left sidebar, select Search or go to and find your group.
- Select Operate > Kubernetes.
Cluster management project
Attach a cluster management project
to your cluster to manage shared resources requiring cluster-admin
privileges for
installation, such as an Ingress controller.
RBAC compatibility
- Introduced in GitLab 11.4.
- Project namespace restriction was introduced in GitLab 11.5.
For each project under a group with a Kubernetes cluster, GitLab creates a restricted
service account with edit
privileges
in the project namespace.
Cluster precedence
If the project’s cluster is available and not disabled, GitLab uses the project’s cluster before using any cluster belonging to the group containing the project. In the case of subgroups, GitLab uses the cluster of the closest ancestor group to the project, provided the cluster is not disabled.
Multiple Kubernetes clusters
- Introduced in GitLab 13.2.
You can associate more than one Kubernetes cluster to your group, and maintain different clusters for different environments, such as development, staging, and production.
When adding another cluster, set an environment scope to help differentiate the new cluster from your other clusters.
GitLab-managed clusters
- Introduced in GitLab 11.5.
- Became optional in GitLab 11.11.
You can choose to allow GitLab to manage your cluster for you. If GitLab manages your cluster, resources for your projects are automatically created. See the Access controls section for details on which resources GitLab creates for you.
For clusters not managed by GitLab, project-specific resources aren’t created automatically. If you’re using Auto DevOps for deployments with a cluster not managed by GitLab, you must ensure:
- The project’s deployment service account has permissions to deploy to
KUBE_NAMESPACE
. -
KUBECONFIG
correctly reflects any changes toKUBE_NAMESPACE
(this is not automatic). EditingKUBE_NAMESPACE
directly is discouraged.
Clearing the cluster cache
- Introduced in GitLab 12.6.
If you choose to allow GitLab to manage your cluster for you, GitLab stores a cached version of the namespaces and service accounts it creates for your projects. If you modify these resources in your cluster manually, this cache can fall out of sync with your cluster, which can cause deployment jobs to fail.
To clear the cache:
- On the left sidebar, select Search or go to and find your group.
- Select Operate > Kubernetes.
- Select your cluster.
- Expand Advanced settings.
- Select Clear cluster cache.
Base domain
- Introduced in GitLab 11.8.
Domains at the cluster level permit support for multiple domains
per multiple Kubernetes clusters When specifying a domain,
this is automatically set as an environment variable (KUBE_INGRESS_BASE_DOMAIN
) during
the Auto DevOps stages.
The domain should have a wildcard DNS configured to the Ingress IP address. More details.
Environment scopes
Offering: GitLab.com, Self-managed, GitLab Dedicated
When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with environments similar to how the environment-specific CI/CD variables work.
While evaluating which environment matches the environment scope of a cluster, cluster precedence takes effect. The cluster at the project level takes precedence, followed by the closest ancestor group, followed by that groups’ parent and so on.
For example, if your project has the following Kubernetes clusters:
Cluster | Environment scope | Where |
---|---|---|
Project | *
| Project |
Staging | staging/*
| Project |
Production | production/*
| Project |
Test | test
| Group |
Development | *
| Group |
And the following environments are set in the .gitlab-ci.yml
file:
stages:
- test
- deploy
test:
stage: test
script: sh test
deploy to staging:
stage: deploy
script: make deploy
environment:
name: staging/$CI_COMMIT_REF_NAME
url: https://staging.example.com/
deploy to production:
stage: deploy
script: make deploy
environment:
name: production/$CI_COMMIT_REF_NAME
url: https://example.com/
The result is:
- The Project cluster is used for the
test
job. - The Staging cluster is used for the
deploy to staging
job. - The Production cluster is used for the
deploy to production
job.
Cluster environments
Offering: GitLab.com, Self-managed, GitLab Dedicated
For a consolidated view of which CI environments are deployed to the Kubernetes cluster, see the documentation for cluster environments.
Security of runners
For important information about securely configuring runners, see Security of runners documentation for project-level clusters.
More information
For information on integrating GitLab and Kubernetes, see Kubernetes clusters.