Connecting a Kubernetes cluster with GitLab

Version history
  • Introduced in GitLab 13.4.
  • Support for grpcs introduced in GitLab 13.6.
  • Agent server introduced on GitLab.com under wss://kas.gitlab.com through an Early Adopter Program in GitLab 13.10.
  • Introduced in GitLab 13.11, the GitLab agent became available on GitLab.com.
  • Moved from GitLab Premium to GitLab Free in 14.5.
  • Renamed from “GitLab Kubernetes Agent” to “GitLab agent for Kubernetes” in GitLab 14.6.
  • Flux recommended as GitOps solution in GitLab 15.10.

You can connect your Kubernetes cluster with GitLab to deploy, manage, and monitor your cloud-native solutions.

To connect a Kubernetes cluster to GitLab, you must first install an agent in your cluster.

The agent runs in the cluster, and you can use it to:

  • Communicate with a cluster, which is behind a firewall or NAT.
  • Access API endpoints in a cluster in real time.
  • Push information about events happening in the cluster.
  • Enable a cache of Kubernetes objects, which are kept up-to-date with very low latency.

For more details about the agent’s purpose and architecture, see the architecture documentation.

Workflows

You can choose from two primary workflows. The GitOps workflow is recommended.

GitOps workflow

You should use Flux for GitOps. To get started, see Tutorial: Set up Flux for GitOps

GitLab CI/CD workflow

In a CI/CD workflow:

  • You configure GitLab CI/CD to use the Kubernetes API to query and update your cluster.

This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster.

Use this workflow:

  • When you have a heavily pipeline-oriented processes.
  • When you need to migrate to the agent but the GitOps workflow cannot support the use case you need.

This workflow has a weaker security model and is not recommended for production deployments.

Supported Kubernetes versions for GitLab features

GitLab supports the following Kubernetes versions. If you want to run GitLab in a Kubernetes cluster, you might need a different version of Kubernetes:

You can upgrade your Kubernetes version to a supported version at any time:

  • 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported)
  • 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported)
  • 1.24 (support ends on July 22, 2023 or when 1.27 becomes supported)

GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor versions at any given time.

When installing the agent, use a Helm version compatible with your Kubernetes version. Other versions of Helm might not work. For a list of compatible versions, see the Helm version support policy.

Support for deprecated APIs can be removed from the GitLab codebase when we drop support for the Kubernetes version that only supports the deprecated API.

Some GitLab features might work on versions not listed here. This epic tracks support for Kubernetes versions.

Migrate to the agent from the legacy certificate-based integration

Read about how to migrate to the agent for Kubernetes from the certificate-based integration.