Skip to main content
In this guide, we’ll review how to install and configure the GitLab Agent in your Kubernetes cluster. The GitLab Agent establishes a secure, real-time connection (via KAS) to clusters—even those behind firewalls—so you can manage deployments and GitOps workflows directly from GitLab. Full documentation:

​
Prerequisites

  • A GitLab project with Owner or Maintainer role
  • kubectl configured to target your cluster
  • Helm 3 installed locally

​
1. Navigate to Kubernetes Integration

  1. In your GitLab project, select Operate → Kubernetes clusters.
  2. Click Connect a cluster (skip the managed-cluster wizard if you already have one).

​
2. Verify Local Cluster Access

Confirm you can reach the cluster from your terminal:
CommandPurpose
kubectl get nodesList cluster nodes
kubectl config get-contextsShow active context
kubectl get namespacesList existing namespaces
kubectl get nodes
kubectl config get-contexts
kubectl get namespaces
At this point, you should see no agent-related namespaces.

​
3. Create a New Agent in GitLab

In the Connect a cluster dialog:
  1. Choose Add an agent configuration → Create a new agent.
  2. Enter a name (for example, kk-gitlab-agent).
  3. Click Create agent to generate a one-time access token.
Copy and securely store the generated token now—this value is shown only once.
The image shows a GitLab interface with a pop-up window for connecting a Kubernetes cluster, where a user is entering a name for a new agent.

​
4. Install the Agent via Helm

Add the GitLab Helm repo and deploy the agent chart: 
helm repo add gitlab https://charts.gitlab.io
helm repo update

helm upgrade --install kk-gitlab-agent gitlab/gitlab-agent \
  --namespace gitlab-agent-kk-gitlab-agent \
  --create-namespace \
  --set image.tag=v16.9.0-rc2 \
  --set config.token=<YOUR_AGENT_TOKEN> \
  --set config.kasAddress=wss://kas.gitlab.com
This command will:
  • Add and update the GitLab charts repository
  • Install (or upgrade) the kk-gitlab-agent release
  • Create namespace gitlab-agent-kk-gitlab-agent if it doesn’t exist
  • Connect to the GitLab Agent Server (KAS) using your token

​
Verify the Helm Release

# You should see "STATUS: deployed"
helm status kk-gitlab-agent -n gitlab-agent-kk-gitlab-agent

​
5. Inspect Deployed Resources

Check pods, deployments, replica sets, config maps, and secrets: 
kubectl -n gitlab-agent-kk-gitlab-agent get all
kubectl -n gitlab-agent-kk-gitlab-agent get configmap,secrets,ingress
Retrieve the agent token secret in YAML: 
kubectl -n gitlab-agent-kk-gitlab-agent get secret kk-gitlab-agent-token -o yaml

​
6. Confirm Connection in GitLab

Return to Operate → Kubernetes clusters in your project and refresh.
The cluster’s Connection Status should now display Connected and active.
The image shows a GitLab interface displaying Kubernetes cluster details, including connection status, version, and configuration options. There's also a notification about Google Cloud Platform credits and a feedback section.
By default, GitLab applies the agent’s built-in config. To customize it, create a file at:
.gitlab/agents/kk-gitlab-agent/config.yaml
Refer to the official documentation for configuration options.

​
Next Steps

  • Define a custom config.yaml to enable GitOps and environment deployments
  • Create and annotate environments to surface cluster metrics in the GitLab UI
Happy deploying!

Watch Video