Skip to content

GitLab

Connecting a Kubernetes cluster with GitLab

  • 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.

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.

In a GitOps workflow, you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and any time you update your manifests, the agent updates the cluster. This workflow is fully driven with Git and is considered pull-based, because the cluster is pulling updates from your GitLab repository.

In a CI/CD workflow, you use GitLab CI/CD to query and update your cluster by using the Kubernetes API. This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster.

Supported cluster versions

GitLab supports the following Kubernetes versions. You can upgrade your Kubernetes version to a supported version at any time:

  • 1.22 (support ends on March 22, 2023)
  • 1.21 (support ends on November 22, 2022)
  • 1.20 (support ends on July 22, 2022)

GitLab supports at least two production-ready Kubernetes minor versions at any given time. GitLab regularly reviews the supported versions and provides a three-month deprecation period before removing support for a specific version. The list of supported versions is based on:

This epic tracks support for other Kubernetes versions.

Some GitLab features might work on versions not listed here.

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.

Related topics