Group-level Kubernetes clusters

GitLab 11.6で導入されました

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.

Installing applications

GitLab can install and manage some applications in your group-level cluster. For more information on installing, upgrading, uninstalling, and troubleshooting applications for your group cluster, see GitLab Managed Apps.

RBAC compatibility

Version history

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 sub-groups, GitLab uses the cluster of the closest ancestor group to the project, provided the cluster is not disabled.

Multiple Kubernetes clusters

Version history

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

You can choose to allow GitLab to manage your cluster for you. If GitLab manages your cluster, resources for your projects will be 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 won’t be 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 to KUBE_NAMESPACE (this is not automatic). Editing KUBE_NAMESPACE directly is discouraged.
Note: If you install applications on your cluster, GitLab creates the resources required to run them even if you choose to manage your own cluster.

Clearing the cluster cache

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:

  1. Navigate to your group’s Kubernetes page, and select your cluster.
  2. Expand the Advanced settings section.
  3. Click 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 will be 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.

Environment scopes

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 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 .gitlab-ci.yml:

  - test
  - deploy

  stage: test
  script: sh test

deploy to staging:
  stage: deploy
  script: make deploy
    name: staging/$CI_COMMIT_REF_NAME

deploy to production:
  stage: deploy
  script: make deploy
    name: production/$CI_COMMIT_REF_NAME

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

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 GitLab Runners, see Security of Runners documentation for project-level clusters.


For information on integrating GitLab and Kubernetes, see Kubernetes clusters.