Connecting a Kubernetes cluster with GitLab via agentK

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

Note

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

In your GitLab project, navigate to Operate > Kubernetes clusters.
Click Add Kubernetes cluster and choose GitLab Agent.
Provide a unique Agent name.
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

Warning

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 Block	Description
gitops.manifest_projects	List of repositories with Kubernetes manifests and target namespaces.
gitops.ci_access	Projects allowed to use this agent in CI/CD pipelines.
workspaces	Remote development settings (Enterprise Edition).

Note

Modify config.yaml as code and push changes to your default branch. AgentK watches this file and applies updates automatically.

References

Watch Video

Watch video content