Certificate-based Kubernetes integration sunsetting on GitLab.com

Note: In a previously published version of this article, we stated that the certificate-based Kubernetes integration would be sunset in GitLab 18.0 in May 2025. That timeline has been extended to GitLab 19.0, planned for May 2026. See the deprecation notice for details.

The certificate-based Kubernetes integration was deprecated in GitLab November 2021, and is available on GitLab.com only to previous users. In May 2026, the integration will sunset on GitLab.com and will stop working. Customers often use the integration to deploy applications to production and non-production environments. As a result, failure to migrate to other options could cause a critical incident in your application delivery pipelines. This post outlines the alternative features that GitLab offers, points out how you can identify the potential impact on your GitLab.com groups and projects, and offers links to the GitLab documentation to learn more about the necessary migration steps.

Recommended alternative: The GitLab agent for Kubernetes

The GitLab agent for Kubernetes represents a significant advancement over the certificate-based integration, offering enhanced security, reliability, and functionality. Here are the key benefits of migrating to the agent-based approach:

Enhanced security

• Eliminates the need for storing cluster credentials in GitLab
• Provides secure, bidirectional communication between GitLab and your clusters
• Supports fine-grained access control and authorization policies
• Enables secure GitOps workflows with pull-based deployments

Improved reliability

• Maintains persistent connections, reducing deployment failures
• Handles network interruptions gracefully
• Provides better logging and troubleshooting capabilities
• Supports automatic reconnection and state recovery

Advanced features

• Real-time cluster information integrated into the GitLab UI
• Integration with GitLab CI/CD pipelines
• Support for multiple clusters and multi-tenant environments
• Enhanced GitOps capabilities by integrating with FluxCD

Get started with the GitLab agent for Kubernetes

If you haven't tried the GitLab Agent for Kubernetes yet, we strongly recommend going through the getting started guides. These guides will walk you through the basic setup and help you understand how the agent works in your environment. The hands-on experience will help make the migration process smoother.

Impact assessment

We implemented a dedicated API endpoint to query all the certificate-based clusters within a GitLab group hierarchy. We recommend starting with this API to see if you have any clusters that need to be migrated.

Once you identify the clusters, you should:

1. Find group and project owners using the certificate-based integration.
2. Check CI/CD pipelines for direct Kubernetes API calls.
3. Identify Auto DevOps projects using the old integration.
4. List any GitLab-managed clusters in use.
5. Set up the agent in the affected clusters.
6. Follow the guidance provided in this post and record your progress in a tracking issue.

Update your CI/CD integration

The legacy certificate-based integration works using GitLab CI/CD. Because the agent seamlessly integrates with GitLab CI/CD pipelines, you can use it to replace the certificate-based integration with relatively little effort. The agent-based CI/CD integration offers several improvements over the certificate-based approach:

1. Direct cluster access: CI/CD jobs can interact with clusters through the agent without requiring separate credentials.
2. Enhanced security: You don't need to store cluster credentials in CI/CD variables.
3. Simplified configuration: A single agent configuration file manages all cluster interactions.
4. Better performance: Persistent connections reduce deployment overhead.
5. Flexible authorization: On GitLab Premium and Ultimate, you can rely on impersonation features to restrict CI/CD jobs in the cluster.

At a high level, there are three steps to migrating your existing CI/CD pipelines:

1. Set up the agent by following the getting started guides.
2. Share the agent connection with the necessary groups and projects..
3. Select the agent in the pipeline jobs.

You can read more about migrating Kubernetes deployments in general or about the agent CI/CD integration in the documentation.

Migrate your Auto DevOps configuration

Auto DevOps is a set of CI/CD templates that are often customized by users. With Auto DevOps, you can automatically configure your CI/CD pipelines to build, test, and deploy your applications based on best practices. It's commonly used with the certificate-based integration for deploying applications to Kubernetes clusters.

If you use Auto DevOps and you rely on the certificate-based integration, you need to transition to the agent-based deployment mechanism. The migration process is straightforward:

1. Set up the CI/CD integration as described above.
2. Configure the KUBE_CONTEXT environment variable to select an agent.
3. Remove the old certificate-based cluster integration.

You can read more about using Auto DevOps with the agent for Kubernetes in the documentation.

Transition from GitLab-managed clusters to GitLab-managed Kubernetes resources

With GitLab-managed clusters, GitLab automatically creates and manages Kubernetes resources for your projects. When you allow GitLab to manage your cluster, it creates RBAC resources like a Namespace and ServiceAccount.

If you use GitLab-managed clusters, you should transition to GitLab-managed Kubernetes resources, which offers a more flexible and secure approach to cluster management.

To migrate:

1. Document your existing cluster configuration.
2. Create corresponding Kubernetes resource definitions.
3. Store configurations in your repository.
4. Configure the GitLab agent to manage these resources.
5. Verify resource management and deployment.
6. Remove the old cluster integration.

You can read more about GitLab-managed Kubernetes resources in the documentation.

Manage cloud provider clusters created through GitLab

If you created Kubernetes clusters through the GitLab integration with Google Kubernetes Engine (GKE) or Amazon Elastic Kubernetes Service (EKS), these clusters were provisioned in your respective cloud provider accounts. After the certificate-based integration is removed:

1. Your clusters will remain fully operational in Google Cloud or AWS.
2. You will need to manage these clusters directly through your cloud provider's console:
   • GKE clusters through Google Cloud Console
   • EKS clusters through AWS Management Console

To view cluster information within GitLab:

1. Install the GitLab agent for Kubernetes.
2. Configure the Kubernetes dashboard integration.
3. Check the dashboard for cluster details and resource information.

This change only affects how you interact with the clusters through GitLab – it does not impact the clusters' operation or availability in your cloud provider accounts.

You should still migrate your deployment setups as described above.

What should I do next?

To minimize the impact to you and your infrastructure, you should follow these steps:

1. Check if you are impacted as soon as possible.
2. Plan your migration timeline before May 2026.
3. Start with non-production environments to gain experience.
4. Document your current setup and desired state.
5. Test the agent-based approach in a staging environment.
6. Gradually migrate production workloads.
7. Monitor and validate the new setup.

The migration to the GitLab agent for Kubernetes represents a significant improvement in how GitLab interacts with Kubernetes clusters. While the migration requires careful planning and execution, the benefits in terms of security, reliability, and functionality make it a worthwhile investment for your DevSecOps infrastructure.