- Create new cluster
- Add existing cluster
- Configure your cluster
- Disable a cluster
- Remove a cluster
- Access controls
Deprecated in GitLab 14.0.
Deprecated in GitLab 14.0.
As of GitLab 14.0, use Infrastructure as Code to safely create new clusters from GitLab.
Creating clusters from GitLab using cluster certificates is still available on the GitLab UI but was deprecated in GitLab 14.0 and is scheduled for removal in GitLab 15.0. We don’t recommend using this method.
You can create a new cluster hosted in EKS, GKE, on premises, and with other providers using cluster certificates:
- New cluster hosted on Google Kubernetes Engine (GKE).
- New cluster hosted on Amazon Elastic Kubernetes Service (EKS).
To host them on premises and with other providers, you can use Terraform or your preferred tool of choice to create and connect a cluster with GitLab. The GitLab Terraform provider supports connecting existing clusters using the certificate-based connection method.
As of GitLab 14.0, use the GitLab Kubernetes Agent to connect your cluster to GitLab.
As of GitLab 14.0, use the GitLab Kubernetes Agent to configure your cluster.
When you successfully create a new Kubernetes cluster or add an existing one to GitLab, the cluster connection to GitLab becomes enabled. To disable it:
- Go to your:
- Project’s Infrastructure > Kubernetes clusters page, for a project-level cluster.
- Group’s Kubernetes page, for a group-level cluster.
- Menu > Admin > Kubernetes page, for an instance-level cluster.
- Select the name of the cluster you want to disable.
- Toggle GitLab Integration off (in gray).
- Click Save changes.
Introduced in GitLab 12.6, you can remove cluster integrations and resources.
When you remove a cluster integration, you only remove the cluster relationship
to GitLab, not the cluster. To remove the cluster itself, visit your cluster’s
GKE or EKS dashboard to do it from their UI or use
You need at least Maintainer permissions to your project or group to remove the integration with GitLab.
When removing a cluster integration, you have two options:
- Remove integration: remove only the Kubernetes integration.
- Remove integration and resources: remove the cluster integration and all GitLab cluster-related resources such as namespaces, roles, and bindings.
To remove the Kubernetes cluster integration:
- Go to your cluster details page.
- Select the Advanced Settings tab.
- Select either Remove integration or Remove integration and resources.
There was a problem authenticating with your cluster. Please ensure your CA Certificate and Token are valid
If you encounter this error while adding a Kubernetes cluster, ensure you’re properly pasting the service token. Some shells may add a line break to the service token, making it invalid. Ensure that there are no line breaks by pasting your token into an editor and removing any additional spaces.
You may also experience this error if your certificate is not valid. To check that your certificate’s subject alternative names contain the correct domain for your cluster’s API, run this:
echo | openssl s_client -showcerts -connect kubernetes.example.com:443 2>/dev/null | openssl x509 -inform pem -noout -text
Note that the
-connect argument expects a
host:port combination. For example,
https://kubernetes.example.com would be