Feb 22, 2021 - Viktor Nagy    

A new era of Kubernetes integrations on GitLab.com

The GitLab Kubernetes Agent enables secure deployments from GitLab SaaS to your Kubernetes cluster and provides deep integrations of your cluster to GitLab.

Read the documentation to get started

The GitLab Kubernetes Agent provides a secure connection between a GitLab instance and a Kubernetes cluster, and allows pull-based deployments to receive alerts based on the network policies. We released the first version of the GitLab Kubernetes Agent ("the Agent") back in September on self-managed GitLab instances. We are happy to announce that the Agent is available on GitLab SaaS, GitLab.com, and has many more features coming soon.

The Agent on GitLab.com is currently available only to selected customers. If you would like to try it out, reach out to me, Viktor Nagy. I am the responsible Product Manager and will authorize your project.

Why a new era?

Before, the recommended way to attach a cluster to GitLab was to provide the cluster certificates and to open up the Kube API to GitLab.com. To get the most out of the integrations, we recommended attaching the cluster with cluster-admin rights, so GitLab could provision new namespaces and create review apps. But many users found this to be overly risky and instead rolled out custom integrations that were often built around the GitLab Runner. We want to simplify and support security-minded users with the GitLab Kubernetes Agent and provide them with a safe, reliable and future-proof integration solution between GitLab and their clusters. The GitLab Kubernetes Agent provides a secure connection between the cluster and GitLab. Access rights can be controlled with the Agent more tightly by our users, and we consider it to be the basis for future Kubernetes integrations with GitLab.

When Kubernetes was just starting to get popular, our initial approach served new Kubernetes users well. At the same time, providing cluster-admin rights is not an option for many current users with experienced Site Reliability Engineers (SREs) and Platform Engineers on board. In the past few years, thanks to the certificate-based integrations, we have learned a lot about the needs of GitLab users, and we are leveraging these learnings with the GitLab Kubernetes Agent.

How does the Agent work?

The Agent provides a permanent connection using websockets or gRPC between a Kubernetes cluster and a GitLab instance. Since we want to keep the cluster-side component minimal and lightweight, we imagine multiple Agents being installed into the same cluster with different access levels. Still, this integration is complex. To understand how the Agent works, let me first introduce its major components. The whole GitLab Kubernetes Agent experience is made possible primarily by two components that we call agentk and kas (short for Kubernetes Agent Server). agentk is the cluster-side component that has to be deployed in the cluster, while kas is the GitLab server-side component that is managed alongside GitLab. Since we want to keep the cluster-side component as slim as possible, kas is responsible for much of the heavy-lifting.

The Agent is configured in code, then registered with GitLab through an access token. Once installed in the cluster, agentk receives the access token and the kas endpoint and authenticates itself with GitLab. Subsequently, it retrieves its own configuration from GitLab, and keeps a connection open between kas and the cluster. This way both the agent and GitLab can send messages and receive information from the other party through a secure connection. This approach also allows a Kubernetes cluster sitting behind a firewall to be securely integrated with GitLab.com.

Getting started

About the Agent's availability

If you would like to try out the GitLab Kubernetes Agent on GitLab.com, kas is already installed and is managed by our SRE team. Before making the Agent generally available, we want to make sure that Agent-based workflows won't harm the performance of GitLab.com. This is why, at this time, kas is only available for select customers and projects. If you would like to try it out, reach out to me in e-mail or by mentioning me in an issue with your project ID, and we will authorize your project.

GitLab's kas instance is available at wss://kas.gitlab.com. You will have to provide this value together with a registered agent access token when you deploy agentk to your cluster. You can follow the installation instructions from our documentation starting with defining a configuration repository.

How deployments work

If you prefer a video walk-through, we demonstrate how pull-based deployments work with the Agent below.

For deployments, we share some codebase with ArgoCD since this part of the Agent is built on the gitops-engine. The gitops-engine provides a simple tool to keep git repositories synced with cluster resources. The Agent is configured in code. What we call the "agent configuration project" references the repositories containing the Kubernetes manifests which are the resource definitions describing the expected state of your cluster. Whenever these manifests change, the Agent automatically pulls the new configuration and applies it in the cluster.

An example using Helm

Today, the GitLab Kubernetes Agent only supports pull-based deployments, but we are working on connecting it with GitLab CI to also provide push-based deployment support. So far, we have created a simple example repository that shows how someone might use the Agent together with Helm to install the GitLab Runner in their cluster.

One critique of Helm is that you might get different deployments without changing anything in the code you manage. We want to make sure that your manifest projects reflect what is expected to be deployed in your cluster. This is why we recommend that you use GitLab CI to generate and commit the final Kubernetes manifests from your preferred templating tool, and let the Agent take care of deploying the rendered templates. We follow this pattern in the example repository too.

Kubernetes network security alerts

In GitLab 13.9 we are shipping an integration with Cilium built on top of the Agent. The integration provides a simple way to generate network policy-related alerts and to surface those alerts in GitLab. Watch the video below for a demo:

Ongoing developments

While we think that the GitLab Kubernetes Agent can already bring great value to Silver and Gold-level GitLab users, we are working constantly to build even more features on top of it.

Our primary focus now is to make the Agent generally available on GitLab.com SaaS. We are also working on a set of features that allows a user to connect GitLab CI with clusters securely using the Agent. This allows existing push-based deployments to start easily using the Agent and the integrations coming with it.

We are excited to see how you will benefit from the GitLab Kubernetes Agent and what amazing things you will build with it.

Guide to the Cloud Harness the power of the cloud with microservices, cloud-agnostic DevOps, and workflow portability. Learn more

Try all GitLab features - free for 30 days

GitLab is more than just source code management or CI/CD. It is a full software development lifecycle & DevOps tool in a single application.

Try GitLab Free
Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license

Try GitLab risk-free for 30 days.

No credit card required. Have questions? Contact us.

Gitlab x icon svg