KodeKloud Notes

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:

Connecting your clusters: https://docs.gitlab.com/ee/user/clusters/agent/
GitOps with FluxCD in GitLab CI/CD: https://docs.gitlab.com/ee/user/clusters/agent/gitops_with_fluxcd.html

Prerequisites

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

1. Navigate to Kubernetes Integration

In your GitLab project, select Operate → Kubernetes clusters.
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:

Command	Purpose
`kubectl get nodes`	List cluster nodes
`kubectl config get-contexts`	Show active context
`kubectl get namespaces`	List 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:

Choose Add an agent configuration → Create a new agent.
Enter a name (for example, kk-gitlab-agent).
Click Create agent to generate a one-time access token.

Warning

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.

Note

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

Watch video content