Skip to main content
In this guide, you’ll learn how to leverage the GitLab Kubernetes Agent (AgentK) for secure, bi-directional connectivity between your Kubernetes clusters and GitLab. AgentK eliminates the need to store raw Kubeconfig credentials in CI/CD variables, simplifies firewall/NAT traversal, and lays the foundation for GitOps-style workflows.

​
Why Use the GitLab Kubernetes Agent?

Traditionally, CI/CD pipelines use a stored Kubeconfig file to authenticate against Kubernetes. However:
  • Kubeconfig files contain sensitive data (API server URL, tokens, certificates).
  • Storing them as masked variables still poses a risk if compromised.
  • Connecting to clusters behind firewalls or NAT gateways can be complex.
AgentK solves these challenges by initiating an outbound gRPC connection to GitLab’s Agent Server (KAS), enabling:
  • Secure, credential-free communication
  • Firewall/NAT traversal without port forwarding
  • Bi-directional streaming for push and pull operations
AgentK is a lightweight pod running inside your cluster. It uses a token-based handshake with KAS to establish a persistent, encrypted channel—removing the need for direct API server exposure.
The image is a diagram illustrating the GitLab Kubernetes Agent architecture, showing the interaction between the GitLab server, CI/CD variables, pipelines, and multiple Kubernetes environments (dev, prod, staging) via gRPC bidirectional streaming.

​
Prerequisites

  • A GitLab account with Maintainer or Owner access.
  • A GitLab project to register the agent and store its configuration.
  • A Kubernetes cluster v1.17+ (AgentK compatibility).
  • helm CLI installed locally.

​
1. Register the GitLab Agent

  1. In your GitLab project, navigate to Operate > Kubernetes clusters.
  2. Click Add Kubernetes cluster and choose GitLab Agent.
  3. Provide a unique Agent name.
  4. GitLab will display a token and the Helm commands required for installation.

​
2. Install AgentK via Helm

Copy the Helm commands from the GitLab UI and execute them with your token: 
helm repo add gitlab https://charts.gitlab.io
helm repo update

helm upgrade --install my-agent gitlab/gitlab-agent \
  --namespace gitlab-agent \
  --create-namespace \
  --set config.token=<YOUR_AGENT_TOKEN> \
  --set config.kasAddress=wss://kas.gitlab.com \
  --set image.tag=v16.9.0
Keep your <YOUR_AGENT_TOKEN> secret. Rotate the token if it is ever exposed.
After installation, AgentK will connect to GitLab automatically. You should see the agent status under Operate > Kubernetes clusters.

​
3. Configure the Agent

AgentK’s behavior is defined in your project’s repository at .gitlab/agent/<agent-name>/config.yaml. Customize this file to control deployments, security, and remote workspaces. 
gitops:
  # Projects containing Kubernetes manifests to deploy
  manifest_projects:
    - id: gitlab-org/my-project
      default_namespace: production

  # Which projects can trigger CI/CD through this agent
  ci_access:
    projects:
      - id: gitlab-org/my-project

# Remote development (GitLab EE only)
workspaces:
  enabled: true
  # configure workspace settings here
Configuration BlockDescription
gitops.manifest_projectsList of repositories with Kubernetes manifests and target namespaces.
gitops.ci_accessProjects allowed to use this agent in CI/CD pipelines.
workspacesRemote development settings (Enterprise Edition).
Modify config.yaml as code and push changes to your default branch. AgentK watches this file and applies updates automatically.

​
References

Watch Video