Skip to main content
In this lesson you’ll learn what the GitLab Kubernetes Agent is, why to use it, and how it securely connects your Kubernetes clusters to GitLab for GitOps and CI/CD workflows. Many teams historically use a kubeconfig file stored as a CI/CD variable to access a cluster. A kubeconfig contains sensitive information — the API server URL, authentication credentials, and default namespaces — and if leaked an attacker can access the cluster, deploy workloads, delete resources, or exfiltrate data. Even masked CI/CD variables are risky and clusters behind firewalls or NAT can complicate connectivity. The GitLab Kubernetes Agent solves these problems by running a lightweight, cluster-side agent (agentK) that initiates a secure, outbound connection to a GitLab Agent Server (KAS). Because the connection is initiated from inside the cluster, it works across firewalls and NATs and removes the need to expose the Kubernetes API or embed long-lived kubeconfig credentials in external systems.

​
What the GitLab Kubernetes Agent provides

  • Secure, authenticated communication between GitLab and your Kubernetes clusters without exposing the Kubernetes API server or embedding long-lived cluster credentials in CI/CD variables.
  • A lightweight cluster-side component (agentK) that initiates connections outbound, making it firewall/NAT friendly.
  • A centrally updatable server component (KAS) that mediates communication and fetches agent configuration/repository data, avoiding frequent in-cluster upgrades.
You can also think of the benefits in a quick table:

​
Architecture overview

The agent is implemented as a client/server pair:
  • agentK: the Kubernetes cluster-side agent that runs in your cluster and initiates the connection to GitLab.
  • KAS (GitLab Agent Server): the server-side component that accepts agentK connections, authenticates them with GitLab, and fetches the agent configuration and Git data (via Gitaly).
agentK opens a bidirectional gRPC stream to KAS. Because the connection is outbound from the cluster, it bypasses many typical networking restrictions. The bidirectional stream enables both push-style and pull-style GitOps workflows: GitLab can notify the agent of changes and the agent can request actions.

​
KAS responsibilities

  • Authenticate agentK connections by querying GitLab.
  • Retrieve the agent’s configuration and repository data via Gitaly (GitLab’s RPC layer for interacting with Git repositories).
  • Forward requests, responses, and notifications between GitLab and agentK.
A diagram titled "GitLab Kubernetes Agent" showing the GitLab server (CI/CD variables, pipelines and gitaly) on the left and multiple agentk instances on the right deployed to dev, prod and staging Kubernetes clusters. Arrows indicate communication through KAS using gRPC bidirectional streaming.
Because KAS is centrally managed, GitLab can evolve server-side behavior without requiring every cluster to upgrade agentK immediately. Given its lightweight design, GitLab recommends running at least one agentK instance per cluster.

​
Registering an agent — prerequisites and overview

Prerequisites: High-level registration steps:
  1. In your GitLab project UI, navigate to Operate → Kubernetes clusters (or the UI location for Agents) and create a new agent. Give it a unique name.
  2. GitLab generates a secure token for the agent and displays Helm installation instructions (including the KAS address).
  3. Run the provided Helm commands on your Kubernetes cluster. The Helm chart uses the generated token and KAS address to register and connect the agent.
  4. After installation, the agent connects to GitLab and appears in the project’s Kubernetes/Agents section.
  5. Manage the agent configuration in your repository at .gitlab/agents/<agent-name>/config.yaml. This file defines what manifests or projects to watch, CI/CD access, workspaces, and other agent behavior.

​
Example Helm installation

The GitLab Helm chart uses the token and KAS address shown in the GitLab UI. Replace glagent-token and the KAS address with the values produced when you register your agent.

​
Agent configuration (config.yaml)

Create the agent configuration in your project at .gitlab/agents/<agent-name>/config.yaml. This YAML file controls GitOps settings, CI/CD access, and (on GitLab EE) remote development workspaces. Example config.yaml:
Summary of common configuration keys:

​
Security and operational notes

  • Treat the generated agent token (config.token) as a secret: store it only in the GitLab UI when adding the agent and in Kubernetes secrets when installing via Helm.
  • The agent initiates outbound gRPC connections to KAS over TLS (wss:// or https://), so you typically do not need to open inbound ports on your cluster.
  • Keep your agent configuration under version control in the project repository to track changes and enable GitOps workflows.
Using the GitLab Kubernetes Agent removes the need to expose your cluster API and avoids storing long-lived kubeconfig credentials in CI/CD variables. It also simplifies connectivity for clusters behind firewalls or NAT because the agent initiates the connection outbound.

Watch Video