We are deprecating the certificate-based integration with Kubernetes in GitLab 14.5

We are deprecating the certificate-based Kubernetes integration with GitLab and all the features that rely on it. This is the legacy integration, introduced early in 2018, in GitLab 10.4.

In September 2020, we started to build a more robust, secure, forthcoming, and reliable integration with Kubernetes and released the GitLab Agent for Kubernetes, which is the recommended methodology to connect clusters with GitLab.

In this post, we explain the reasons for the change of path, what to expect, and how this affects the features that rely on the certificate-based integration with Kubernetes.

What to expect

The deprecation of the certificate-based Kubernetes integration affects all the features that require a cluster connected to GitLab through cluster certificates. All those features are deprecated. The certificate-based integrations will be switched off on gitlab.com starting with the GitLab 15.0 release. Self-managed users will be able to switch the features back until their final removal. The final removal will happen once all the collected, critical use-cases are supported with the agent and enough time was given for our users to migrate to the agent.

In regards to the existing features that rely on the certificate-based integration:

• Some of the features will be migrated to use the GitLab Agent and we will provide you with migration guides to help you follow along. We will communicate them through the following releases in our release posts, as usual.
• If you already use features that depend on cluster certificates, you can keep using them. But note that you might need to take extras steps in the future to migrate them to the Agent. However, we do not guarantee that we will migrate all the existing certificate-based features to the Agent.
• Existing users should not expect new functionality except for the developments required to support more recent Kubernetes versions, security and critical fixes, and community contributions.
• If you currently do not use a deprecated feature and regardless decide to use it anyway, understand that there's a risk of having to migrate it to the Agent later, or, in the worst-case scenario, you might have to stop using the feature in the future.

See the updated list of the affected features on the docs.

What this deprecation means

The deprecation means that we will not build more features on top of the existing features that depend on cluster certificates. It doesn't mean that the features will stop working right now.

New features for Kubernetes clusters will be built on top of the connection between GitLab and your cluster through the Agent rather than on top of the certificate-based connection.

We have dedicated documentation to support you migrating from the certificate-based connections to agent-based connections.

What should you do for clusters not connected to GitLab yet

To connect new clusters with GitLab, use the Agent so that you don't have to take extra steps to use the Agent later on.

Why we deprecated the certificate-based integration with Kubernetes

There were several reasons why we decided to rethink our approach to Kubernetes:

• The certificate-based integration's biggest shortcoming is that it relies on direct access to the Kubernetes API. Its exposure often comes with unacceptably high risk, especially for GitLab SaaS users.
• The most valuable features within the integration required elevated privileges, often requiring you to give cluster-admin rights to GitLab. At the same time, features that did not need these privileges could not be restricted with more limited access. This means that you had to grant full access to a rather simple feature, which could turn out as a liability.
• Feedback from users implied that many of the features were never ready for production and could be used only in limited situations.
• The industry progressed, and pull-based deployments started to gain ground. And this approach was mostly unknown when we built the integration.

We decided to address all these shortcomings with the GitLab Agent.

The advantages of the GitLab Agent

The integration with Kubernetes through the Agent provides many benefits compared to the certificate-based integration, such as:

• Security
• Reliability
• Scalability
• Speed
• Functionality

Compared to the certificate-based integration, the Agent offers the following functionalities:

• Configure your cluster through code. This enables a clear separation of duties and you can use well-known merge request workflows and approvals.
• An agent can be configured using regular Kubernetes RBAC rules, maintaining access to your cluster safe.
• Scaling to multiple environments is trivial as each agent connects to one environment.
• An agent's connection to a cluster can be shared by other groups and projects to simplify coordination and maintenance.
• The Agent supports pull-based deployments, enabling modern GitOps approaches.
• The Agent supports push-based deployments, enabling existing GitLab CI/CD workflows to remain functional.
• Having a bi-directional channel between GitLab and the cluster enables a new set of integrations, like surfacing container network security policy alerts and container scan results into GitLab.

What is next on the roadmap of the GitLab Agent

We identified a few high-value features on the list of deprecated features. Moreover, we know that having some level of observability around the resources managed by the Agent is its biggest shortcoming. As a result, we are going to focus on the following three items first:

• Provide observability features for cluster resources so you can track your metrics and logs directly from GitLab.
• Auto DevOps and especially Auto Deploy can already by used on top of an Agent-based connection, but the setup is not easy. We will provide you with a solution soon.
• GitLab-Managed Clusters are expected to work as they do today until we ship an equivalent or superior functionality built around the Agent. Together with shipping this functionality, we will provide a migration guide if necessary.

We are listening

Please help us to help you. We need your feedback to help us prioritize the migration of the current features to the Agent and to build new features based on the Agent. We are especially seeking feed back around real-world, high-scale usage of the features built for using Kubernetes clusters with GitLab.

If you would be open to sharing your feedback, please start a new thread in this epic. Feel free to mention @nagyv-gitlab in your comment to make sure that your comment is read and the information won't be missed.