Kubernetes clusters

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

To connect clusters to GitLab, use the GitLab agent for Kubernetes.

Certificate-based Kubernetes integration (deprecated)

[!warning] In GitLab 14.5, the certificate-based method to connect Kubernetes clusters to GitLab was deprecated, as well as its related features. In GitLab Self-Managed 17.0 and later, this feature is disabled by default. For GitLab.com users, this feature is available until GitLab 15.9 for users who have at least one certificate-based cluster enabled in their namespace hierarchy. For GitLab.com users that never used this feature previously, it is no longer available.

The certificate-based Kubernetes integration with GitLab is deprecated. This integration had the following issues:

• There were security issues as it required direct access to the Kubernetes API by GitLab.
• The configuration options weren't flexible.
• The integration was flaky.
• Users were constantly reporting issues with features based on this model.

For this reason, the certificate-based integration was deprecated to focus on the new model, GitLab agent for Kubernetes. Maintaining both methods in parallel caused a lot of confusion and significantly increased the complexity to use, develop, maintain, and document them. As a result, both were deprecated in favor of the new model. Certificate-based features continue to:

• Receive security and critical fixes.
• Work with supported Kubernetes versions.

The removal of these features from GitLab is not scheduled yet.

Follow this epic for updates.

If you need more time to migrate to the GitLab agent for Kubernetes, you can enable the feature flag named certificate_based_clusters, which was introduced in GitLab 15.0. This feature flag re-enables the certificate-based Kubernetes integration.

Deprecated features

• Connect an existing cluster through cluster certificates
• Access controls
• GitLab-managed clusters
• Deploy applications through certificate-based connection
• Cluster Management Project
• Cluster environments
• Show Canary Ingress deployments on deploy boards
• Deploy Boards
• Web terminals

Cluster levels

The concept of project-level, group-level, and instance-level clusters becomes extinct in the new model, although the functionality remains to some extent.

The agent is always configured in a single GitLab project and you can expose the cluster connection to other projects and groups to access it from GitLab CI/CD. By doing so, you are granting these projects and groups access to the same cluster, which is similar to group-level clusters' use case.