How the GitLab agent for Kubernetes connects your clusters to GitLab
A platform team running self-managed GitLab usually wants deployment jobs to reach its Kubernetes clusters without publishing cluster API servers to the network or handing pipelines long-lived certificates. The GitLab agent for Kubernetes is built for that split. The agent, called agentk, runs as a workload inside each cluster. The matching server side, KAS (the Kubernetes Agent Server), runs as part of your GitLab instance. Each cluster is registered with GitLab as an agent, and the two components then carry the traffic between them, so the cluster's API server is not exposed to GitLab directly.
The connection runs in the direction that matters for your firewall policy. agentk opens the connection to KAS and keeps it open, so GitLab does not need an inbound route into the cluster. Requests from GitLab travel back to the agent over that channel. The outbound path from each cluster to your GitLab host is the first dependency to plan. In an air-gapped or segmented network, confirm which addresses and ports the agent must reach in the version you run, and confirm them in the GitLab agent documentation rather than assuming defaults. Also confirm how the agent registration token is created, stored and rotated, because that token identifies the cluster to your instance.
Once the connection is open, the agent's authority is set by Kubernetes, not by GitLab. Kubernetes does not represent normal users as API objects and authenticates them through certificates, tokens or proxies, so the agent's in-cluster service account and its RBAC bindings decide what a pipeline can change. Before go-live, list the namespaces and verbs your deployment jobs need, bind only those, and check the Secrets your deployments read. Secrets are stored unencrypted in etcd by default, so confirm that encryption at rest is configured. The Kubernetes authentication documentation explains the identity options your team is moving away from.
What you need in place before installing the agent
The agent connects your cluster to a GitLab instance through two pieces that must both be reachable: the agent running in the cluster and KAS on the GitLab side. Most installation failures trace back to a gap in one of the items below, so confirm each before scheduling the install.
GitLab version and tier
Confirm that your self-managed GitLab version includes the agent for Kubernetes features you plan to use, and that the agent version you install matches it. Check the GitLab documentation for the agent on self-managed instances, since feature availability can differ by release. Also confirm which tier covers the access modes you need: the pricing page lists Free, Premium and Ultimate as available for self-managed installations, but tier-specific features must be checked individually. Plan upgrades so GitLab is on a supported version before you add the agent.
Reachable KAS endpoint
The agent opens an outbound connection to the GitLab Agent Server (KAS), so the cluster must be able to reach that endpoint over the network path your firewalls allow. Confirm the KAS address your administrator exposes, the TLS certificate it presents, and whether traffic passes through a load balancer or ingress. Test reachability from a pod inside the target cluster, not from your workstation, because cluster egress rules often differ.
Cluster access for the installer
Whoever runs the install needs enough Kubernetes permission to create the agent namespace, deployment, service account and RBAC bindings. Confirm the installer's role in the target cluster and whether a platform team must approve cluster-scoped objects. Keep this access separate from the long-term access granted to the agent, so that the setup credentials are not retained after installation.
Kubernetes versions in support
Only install against a cluster running a Kubernetes minor version the project still maintains. The project maintains the three most recent minor releases; as of September 2026 these were 1.37, 1.36 and 1.35, with end of life dates running into 2027. Older clusters should be upgraded first, one minor version at a time, following the version skew policy. Confirm the exact version your agent release supports in the GitLab documentation before you rely on it.
Certificates and proxies for air-gapped networks
In offline or restricted networks, the agent image must come from a registry you host, and the GitLab instance and KAS must trust your internal certificate authority. Confirm how the agent image is mirrored, which CA bundle the cluster needs, and whether an HTTP proxy sits between the cluster and KAS. Also confirm that proxy settings do not intercept the long-lived gRPC connection, because a broken connection stops cluster management without an obvious error.
Legacy certificate-based access
If any cluster is still connected through certificate-based Kubernetes integration, record which workloads and pipelines depend on it before you add the agent. Kubernetes authenticates users with X.509 certificates, tokens or proxies, so the agent introduces a different trust path. Plan the cut-over with a parallel period, confirm which pipelines switch, and remove the old credentials once the agent path is verified.
GitOps with Flux or CI/CD access: which pattern fits your team
A platform team that wants every cluster change traced to a reviewed commit usually fits GitOps with Flux. In this pattern, a controller inside the cluster pulls the desired state from a Git repository and applies it. Application teams propose changes through merge requests and never need direct cluster credentials.
- Credential ownership: The controller holds the access it needs inside the cluster, so pipelines and developers do not need standing cluster credentials.
- Drift detection: The controller compares live state with the repository and reports or reverts manual edits, depending on how it is configured.
- Rollback: Rollback is a Git revert followed by reconciliation, so the repository history becomes the cluster change history.
- Ongoing load: The platform group owns the repository layout, controller upgrades and the secrets design, because plaintext values must never be committed.
Confirm with your platform group that it can staff ongoing ownership of the repository structure and the controller lifecycle before you choose this pattern.
Teams that release several times a day often prefer CI/CD access, because the pipeline that builds an image can also deploy it. The pipeline reaches the cluster through the access grants configured for the GitLab agent. The decision then depends on how tightly you need the cluster state to be continuously enforced.
- Credential ownership: The GitLab administrators and the project maintainers decide which projects and environments can reach each cluster, so the grant configuration becomes a governed setting.
- Drift detection: The pipeline checks state only when it runs, so a manual change made between deployments stays in place until the next job, unless a separate check runs.
- Rollback: Rollback means re-running an earlier deployment job or pipeline, so the pipeline definition and the artifact versions must remain available.
- Protection: Protected branches and protected environments decide who can trigger production deployments, and they need the same review discipline as the code.
Confirm which access grant options your agent version supports and how deployment jobs record the artifact version they applied.
A small team with a few clusters and no dedicated platform engineers can often start with CI/CD access, because it adds fewer components to run. The trade-off is that power over the cluster moves to whoever can change the pipeline configuration. That makes pipeline review a security control, not only a delivery convenience.
- Credential ownership: Cluster reach follows GitLab permissions, so anyone with maintainer rights on the deployment project can change what the pipeline can do.
- Drift detection: Drift is visible only when someone compares the cluster with the expected manifests, so schedule a manual or pipeline-based check.
- Rollback: Rollback depends on keeping prior manifests and image tags reachable, which is easy to lose when pipelines are edited in place.
- Upgrade effort: Fewer controllers means less to upgrade, but the Kubernetes version skew rules still apply to the cluster itself.
Confirm who can edit the pipeline configuration and whether the team can run the check on a schedule without extra tooling.
In regulated settings, the question is which pattern produces the clearest change evidence and separates duties. GitOps keeps a Git history of desired state that reviewers can read directly. CI/CD access keeps job logs and approvals in GitLab, which can also serve as evidence when protected environments are configured well. Either pattern can satisfy an audit, but the controls differ.
- Separation of duties: GitOps separates the people who approve changes from the controller that applies them, while CI/CD access requires protected environments to achieve the same split.
- Drift evidence: A reconciliation controller can show when live state diverged from the repository, which supports incident reviews.
- Rollback evidence: A revert commit shows what was undone and who approved it, while a re-run job shows the earlier artifact that was redeployed.
- Offline operation: GitLab documents offline and air-gapped operation, so confirm that controller and agent images can be mirrored into your registry.
Confirm with your auditors which evidence they will accept before you choose the pattern, because the control design must be documented either way.
Configuring the agent from registration to first deployment
This sequence connects a self-managed GitLab instance to a Kubernetes cluster you control, so that pipelines or Flux can reach the cluster through an agent that runs inside it. Each step ends with a check that confirms the connection before the next one starts.
Confirm the GitLab and cluster prerequisites
Before registering anything, the platform team confirms that the GitLab instance can serve the agent (KAS must be enabled on your self-managed instance), that the cluster runs a Kubernetes version still in support, and that the cluster can make outbound connections to the GitLab instance. Check the agent documentation for the exact KAS and network requirements for your GitLab version, and confirm the supported Kubernetes versions for that release with GitLab. The step is done when the team has written down the GitLab URL, the cluster name and the outbound path the agent will use.
Register the agent in the GitLab project
A maintainer of the project that will hold the agent configuration creates an agent record in the GitLab interface and gives it a name. Registration creates a configuration file in the repository where access rules will be defined later. The step is complete when the agent appears in the project's Kubernetes clusters list with no connection status yet, which is expected until the agent is installed.
Generate the agent access token
Registration produces an access token and an installation command that include the token and the GitLab address. The token authenticates agentk to KAS, so the team should store it in a secure location, limit who can view it, and treat it as a credential that can be rotated. Rotation procedures should be confirmed with GitLab for the version in use. The step is done when the token and installation values are stored where the platform team can retrieve them for the cluster install, without being pasted into a shared repository.
Install agentk into the cluster
An operator with cluster administrator rights installs agentk using the Helm chart or manifest method shown in the GitLab interface, applying the token and GitLab address generated in the previous step. Install it in a dedicated namespace and review the resources it requests and the RBAC it creates. The step is verified when the pods in that namespace are running and the agent shows as connected in the GitLab project, with a recent connection timestamp. If it shows as not connected, check the pod logs for network or token errors before continuing.
Configure access for CI/CD or Flux
The team edits the agent configuration file in the repository to define what the agent can do. For CI/CD access, it sets the user and group access rules that determine which projects and pipelines can use the cluster connection and which Kubernetes permissions they receive. For GitOps with Flux, the team decides which components will reconcile from which repository and configures access for that path. Reviewers should read the RBAC scope before merging, and the step is done when the configuration is merged and GitLab reports the change as applied to the agent.
Run a test deployment through the agent
The team runs a low-risk test in a non-production namespace, such as a pipeline job that lists namespaces or applies a harmless ConfigMap using the kubectl context provided by the agent. The job should run under the project and branch the access rules allow, and it should fail if used from an unauthorized project. The step is complete when the test job reaches the cluster, the expected object appears in the cluster, and a job from an unauthorized context is denied. Keep the test output as evidence for the change record.
How GitLab roles, projects and agent access map to cluster permissions
This table compares each access decision in a GitLab agent setup with the system that enforces it, either GitLab or Kubernetes. Read it as a checklist: for every row, confirm which side owns the setting and check the current agent documentation before you rely on the default. The main takeaway is that GitLab decides who may use the agent, while Kubernetes RBAC decides what the agent can change.
| Access decision | Where it is set | What to confirm |
|---|---|---|
| Which projects can use the agent | GitLab: agent configuration file in the project that hosts it, with access granted to specific projects or groups | Confirm the current access syntax for projects and groups in the agent documentation |
| Who can change agent configuration | GitLab: project roles on the repository holding the agent configuration | Confirm which roles can edit agent files and approve merge requests to them |
| What the agent may do in the cluster | Kubernetes: ClusterRole and RoleBinding objects bound to the service account the agent uses | Confirm the agent's service account and that its bindings are namespace-scoped where possible |
| Identity used by CI/CD jobs | Kubernetes: impersonation or service account mapping defined by the agent configuration | Confirm how job identity maps to Kubernetes users and groups in your agent version |
| Identity used by GitOps deployments with Flux | Kubernetes: the Flux controller service account and its RBAC | Confirm which controllers run with cluster-wide rights and whether each needs them |
| Cluster-side authentication of agentk | Kubernetes: the agent's registration token and its connection to KAS on GitLab | Confirm how tokens are issued, rotated and revoked for your self-managed KAS |
| Protection of cluster secrets | Kubernetes: Secrets RBAC and encryption at rest in etcd | Confirm that list and watch on Secrets is restricted to workloads that need it |
| Certificate-based cluster access being retired | Kubernetes: client certificates and cluster-admin bindings created before migration | Inventory these bindings and confirm the removal steps against the current GitLab migration guidance |
Securing cluster access through the agent
The agent opens an outbound connection from the cluster to GitLab, so the permissions it holds, the projects and branches allowed to use it, and the state of the cluster itself decide how much a compromised pipeline could reach. The controls below work together: narrow the agent's permissions, limit who can reach it, constrain what workloads may run, protect stored Secrets, and review the cluster against a benchmark.
Least-privilege RBAC for agentk
The agent runs in the cluster with a service account whose role bindings decide what GitLab can read or change through it. Grant only the namespaces and verbs the deployment or access workflow needs, and bind them to specific namespaces rather than cluster-wide roles where possible. Review the bindings after each change, and confirm which verbs the agent holds on Secrets, since list and watch access exposes values to anyone who can use the agent.
Project and branch access rules
The agent configuration lists which GitLab projects and groups may use the cluster connection. Keep that list short, and make sure production clusters are reachable only from protected branches and approved projects. Confirm in your instance how branch protection and environment settings interact with agent access for each project, and test that a feature branch from an unrelated project is refused.
Pod Security Standards for workloads
Pods deployed through the agent are subject to the cluster's admission controls, not to GitLab settings. Apply the Pod Security Standards levels to namespaces that receive deployments, starting with a warn or audit mode to find manifests that would fail. Note which namespaces run CI job pods and which run application workloads, since runner-created pods need their own review.
Encryption at rest for Secrets
Kubernetes stores Secrets unencrypted in etcd by default, so anything a pipeline deploys as a Secret is readable by anyone with direct etcd access or a broad read permission. Configure encryption at rest for the API server, confirm that existing Secrets are rewritten after the change, and back up the encryption key separately from etcd snapshots. Decide whether values should come from an external store through the Secrets Store CSI Driver instead.
CIS Kubernetes Benchmark review
The CIS Kubernetes Benchmark is a community checklist of configuration settings for control plane components, worker nodes and policies. Run an assessment against the cluster's version, record each deviation with a reason, and rerun it after cluster upgrades, since defaults can change. Treat the results as input to your own risk decisions, not as an audit report, and confirm the benchmark version that matches your distribution.
Moving off certificate-based cluster connections
Teams move off certificate-based cluster connections because the credentials that GitLab stores for a cluster are long-lived, sit in CI/CD variables that many jobs can read, and grant cluster access that is hard to scope to a single project or branch. The agent for Kubernetes replaces that pattern with an outbound connection from a agentk process running inside the cluster to KAS on your GitLab instance, so no API server credential has to be copied into GitLab. Before you start, inventory every project and group that still uses the old cluster integration, and record which jobs deploy with it, which environments they target and which service accounts their kubeconfig maps to. Kubernetes does not represent normal users as API objects and authenticates them through X.509 client certificates, bearer tokens or other methods, so the certificate or token behind the old integration is a credential you must rotate or revoke on its own schedule, separate from the agent's authorization.
Run the migration as a parallel period, not a switch. Install the agent on a non-production cluster first, grant it access through the agent's configuration file in the cluster-management project with the narrowest RBAC role that the deployment needs, and point one low-risk pipeline at the agent context while the old integration stays in place. Keep the old CI/CD variables and integration enabled until several successful deployments have run through each target environment, and confirm that rollback is a single known action: re-point the job's kubectl context or environment configuration back to the old integration. Confirm with your platform team how long that rollback path must remain available under your change management policy, because no timeline is supplied here.
Remove the old credentials only after every job in the inventory has been moved and the rollback path has been exercised once. Delete the certificate-based integration from each project and group, then remove the matching KUBE_* variables and any copies in downstream tools. Revoke the client certificate or token in the cluster, and confirm that the old service account no longer has bindings in the cluster. Check the audit trail on both sides, because the removal of a variable does not revoke access on its own. Ask your GitLab administrator to confirm which instance and group settings could re-enable the old integration, so the path cannot return silently.
Why the agent shows disconnected or deployments fail
This table lists the failures teams hit most often when the GitLab agent for Kubernetes cannot connect or cannot deploy, with the likely cause and the first fix for each. Read it top to bottom when an agent shows disconnected or a deployment stalls, and check the causes in order because network and certificate faults often look like authorization faults.
| Symptom | Likely cause | First fix |
|---|---|---|
| Agent shows disconnected in GitLab | agentk cannot open an outbound connection to KAS on the self-managed instance, often because of a firewall, DNS name or port that differs from the KAS address configured for the instance | Confirm the KAS address and port from the instance settings, then test outbound reachability from a pod or node in the cluster before changing agent configuration |
| TLS or certificate errors in agentk logs | The instance uses an internal certificate authority that agentk does not trust, or the certificate chain is incomplete or expired | Add the internal CA to the trust store used by agentk, verify the full chain, and renew any expired certificate on the KAS endpoint |
| Connection fails only in air-gapped or proxied networks | An HTTP proxy intercepts or blocks the gRPC connection, or required hostnames are not resolvable inside the isolated network | Confirm with your network team whether the proxy supports long-lived gRPC streams, and resolve the KAS hostname from inside the isolated segment before retesting |
| Deployments are rejected with forbidden errors | The agent's access configuration does not grant the requested namespace or resource to the project, group or CI/CD job that is deploying | Review the agent authorization entries for the project or group, then match the namespace and verbs to what the pipeline actually applies |
| Agent works in one project but not another | Authorization is granted per project or group, so the second project is missing from the agent's allowed list | Add the project or group to the agent authorization configuration and confirm the change in the agent's events before rerunning the pipeline |
| Kubernetes version outside the supported range | The cluster's minor version is too far from the kube-apiserver version the agent or tooling expects, or the cluster is on a version that the project no longer maintains | Check the cluster version against the Kubernetes version skew policy and the currently maintained releases, then plan an upgrade one minor version at a time |
| API server unreachable from the agent | The kube-apiserver address is not reachable from the agent's network, or the load balancer in front of port 6443 is unhealthy | Test the API endpoint from the node running agentk, check the load balancer health checks, and confirm the in-cluster service address the agent is configured to use |
| Control plane stalls or API errors intermittently | etcd has lost quorum, has an even member count, or is slow, which makes the API server fail under load | Check etcd member health and quorum with your cluster tooling, confirm an odd member count, and verify that a recent etcd snapshot exists before any repair |
| Authentication failures against the cluster | Certificate-based access used for the agent or CI/CD jobs has expired, or the credentials were moved to a cluster that no longer trusts them | Confirm the expiry of client certificates, plan the move to agent-based access, and verify which identity Kubernetes sees for the agent |
Questions teams ask before installing the GitLab agent
Does the GitLab agent for Kubernetes need a paid GitLab tier?
The agent itself is part of the GitLab platform, but the features you plan to use decide the tier. GitLab Free costs 0 dollars, Premium costs 29 US dollars per user per month billed annually according to the GitLab pricing page, and Ultimate is custom priced. All three tiers are available for self-managed installations. The pricing page lists advanced CI/CD and priority support for Premium, so ask your GitLab account contact to confirm which agent features map to which tier for your version before you commit to a plan.
What drives the cost of connecting GitLab to Kubernetes?
The cost comes from four areas: the number of clusters, whether you use GitOps with Flux or CI/CD access (or both), the number of environments per cluster, and whether the network is air-gapped. Each cluster needs its own agent configuration, RBAC scope and network path back to your self-managed GitLab instance. Air-gapped work adds image mirroring and offline installation steps, and GitLab documents separate guidance for offline environments. Ask any partner to price these as separate line items with a fixed scope, and to state which parts are one-time setup and which are ongoing operations.
How long does it take to install and configure the agent?
Duration depends on the number of clusters, the access model and the change controls in your environment. A single cluster with one agreed access pattern is a much smaller job than a fleet with GitOps, CI/CD access and separate production approvals. We do not publish durations, so ask for a timeline in the written scope that lists each cluster, each environment and each change window. Your internal reviews and security sign-off often take longer than the technical steps.
What access does our team need to provide before the work starts?
Plan for three kinds of access. Cluster administrators must be able to create the agent namespace, install the agent, and grant it the RBAC permissions you approve. GitLab administrators must be able to register the agent and manage the project or group that holds its configuration. Your change board must schedule windows for installing the agent and for any cluster changes. Confirm in writing who holds each role, who approves production changes, and who can roll back if a change fails.
Can our internal platform team install the agent without outside help?
Yes, a team with Kubernetes and GitLab administration experience can install a single agent on a cluster it already runs. The harder parts are usually the access model, the role boundaries between GitOps and CI/CD, the air-gapped path, and the upgrade plan for both GitLab and Kubernetes. Kubernetes releases roughly three times a year on a cycle of about 14 weeks, so your team must keep the agent and cluster versions in step with the skew policy. Decide early whether your staff can own that routine work for the length of the agreement.
Should we use GitOps with Flux or CI/CD access to the cluster?
Use GitOps when you want the cluster state to be pulled from a repository and reconciled continuously, and use CI/CD access when pipelines need to run deployment commands directly. Many teams use both, but each path widens what the agent can change, so the decision affects RBAC, audit and incident response. Document which namespaces each path may touch before installation. If you run Argo CD already, confirm which tool owns each workload to avoid two controllers fighting over the same resources.
Does the agent work with certificate-based cluster access, and how do we move off it?
Kubernetes does not represent normal users as API objects and authenticates them with X.509 client certificates, bearer tokens, webhook token authentication or an authenticating proxy. Certificate-based access used by older GitLab cluster integrations has to be replaced by the agent model, and the cutover needs a plan for each cluster and environment. Inventory which pipelines and tools use the old credentials, schedule the switch, and remove the old credentials afterward. Confirm the exact supported Kubernetes versions with GitLab for your release, because the agent's compatibility depends on both sides.
What should we confirm in a quote before signing?
Ask for a written scope that lists the GitLab version and tier, each cluster and its Kubernetes version, the GitOps and CI/CD access paths, whether the network is air-gapped, and which environments are included. Ask which costs are one-time setup and which are recurring support or upgrades, and what the client team must provide. Confirm the acceptance criteria, the handover documentation and what happens if a cluster version falls outside supported releases during the work. Engagements are fixed-scope and agreed in writing before work starts.
Where the official GitLab and Kubernetes documentation applies
Start with the Kubernetes version skew policy before you decide which cluster versions the agent will reach. It sets the order in which the API server, controller manager, scheduler and kubelets must be upgraded and how far kubelets may lag behind the API server. Pair that with the Kubernetes authentication documentation, which explains how users are authenticated (client certificates, bearer tokens including OpenID Connect and JWT, webhook token authentication or an authenticating proxy). Those pages answer the questions that matter for the agent: which minor versions your clusters can run while the agent is connected, and which identity model you are moving from when you retire certificate-based access. Confirm against the current Kubernetes release notes for your target versions, because the supported range changes with each release.
The GitLab installation methods page and the GitLab upgrade paths documentation answer the GitLab side of the same plan. The first tells you which install method your instance uses, since the agent server (KAS) behavior and the Helm chart or Linux package setup differ in how components are configured. The second lists the required upgrade stops, so you can confirm that the GitLab version you upgrade to supports the agent configuration you need. Read both before you schedule any change to the instance, and check the GitLab maintenance policy for the currently supported releases. Your checklist should record the GitLab version, the agent version (agentk) and each cluster's Kubernetes version side by side.
How DeployOpen scopes and delivers the GitLab agent integration
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside your own infrastructure, including GitLab. For the GitLab agent for Kubernetes, we agree the access model and cluster scope in writing first, then build and verify the connection in your environment before handing it over.
How we scope
- Inventory the clusters, namespaces and environments the agent should reach, and who may use each one.
- Decide GitOps with Flux or CI/CD access per cluster, with the reasons recorded in the written scope.
- Confirm your self-managed GitLab version, Kubernetes versions and any air-gapped constraints before work starts.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work begins.
How we build
- Install and configure agentk and the GitLab side of the agent connection on your self-managed instance.
- Set RBAC for the agent's service account so it has least-privilege access to each target namespace.
- Plan the migration of certificate-based cluster connections to the agent, with a rollback path for each cluster.
- Test deployments, access denials and failure behavior in a non-production cluster before production cutover.
How we hand over
- Deliver a written record of the agent configuration, access boundaries, RBAC bindings and cluster inventory.
- Document runbooks for rotating agent tokens, upgrading agentk and removing a cluster from GitLab.
- Walk your platform and security teams through verification steps so they can repeat them independently.
- Hand over the Kubernetes version and GitLab upgrade checks your team needs to keep the connection supported.
How we support
- Offer ongoing support, upgrades and continuous testing for the agent integration as a retainer.
- Track Kubernetes version support and GitLab release changes that affect the agent and plan upgrades around them.
- Re-run access and security tests after cluster, RBAC or GitLab changes to confirm boundaries still hold.
- Confirm with your own environment and vendor documentation which features apply to your versions before relying on them.
