Kubernetes Agent, GitOps Workflows, Cluster Access, Environments, and Deployment Integration: Concepts, Architecture, and Mental Model

1. The practical problem: GitLab and Kubernetes are separate security systems

A deployment pipeline can be perfectly governed inside GitLab and still be dangerous at the cluster boundary. GitLab knows projects, members, protected refs, runners, jobs, and environments. Kubernetes knows API identities, service accounts, namespaces, Roles, ClusterRoles, and admission policy. Neither platform automatically converts one permission model into the other.

The GitLab Agent for Kubernetes creates an authenticated communication path between GitLab and a cluster. It does not mean every GitLab Maintainer is a Kubernetes administrator, nor does it make a deployment safe merely because GitLab recorded it.

2. Mental model: project configuration → KAS → agentk → Kubernetes API → RBAC

The agent configuration project contains an optional file at .gitlab/agents/<agent-name>/config.yaml. Registering the agent creates a GitLab-side agent object. Installing agentk in the cluster gives that agent an outbound authenticated connection to KAS, the GitLab Kubernetes Agent Server. CI jobs or users can then use the connection only when GitLab-side authorization and Kubernetes-side authorization both permit the request.

flowchart TD
  G[GitLab project] --> C[Agent config
.gitlab/agents/lab-agent/config.yaml]
  C --> KAS[GitLab KAS
agent server]
  AK[agentk in cluster] <-->|outbound authenticated channel| KAS
  J[CI job] -->|KUBECONFIG context| KAS
  KAS -->|agent connection| AK
  AK -->|Kubernetes API request| API[Kubernetes API]
  API --> RBAC[Kubernetes RBAC]
  RBAC --> NS[Namespace / workload]
  E[GitLab environment] -.records deployment identity.-> J

Every arrow is a distinct control plane. The GitLab project decides which CI jobs may receive an agent context. KAS brokers the request. The installed agent authenticates the connection. Kubernetes RBAC finally decides what the request may do. A failure at any layer can look like “cluster access is broken,” but the correction belongs to the layer that actually denied it.

3. Define the objects before operating them

4. CI/CD access: authorization first, Kubernetes RBAC second

For the basic CI/CD workflow, the agent configuration can authorize specific projects or groups. Authorized jobs receive a generated kubeconfig path in $KUBECONFIG with contexts for their available agents. Current GitLab allows up to 500 authorized projects and 500 groups per connection, and configuration changes can take one or two minutes to propagate.

# .gitlab/agents/lab-agent/config.yaml
ci_access:
  projects:
    - id: training/platform/app
      environments:
        - review/*
        - staging
# Premium/Ultimate optional hardening:
#      access_as:
#        ci_job: {}

The environment filter is important: it narrows which jobs in an authorized project receive access. It is still not Kubernetes RBAC. On Free, the default request identity inherits the permissions of the service account used by the installed agent. Premium/Ultimate adds impersonation such as access_as: { ci_job: {} }, allowing Kubernetes RBAC to distinguish CI job identities more precisely.

5. GitOps in GitLab 19.3 means Flux + Agent, not legacy agent manifest sync

GitOps continuously reconciles declared desired state to observed cluster state. GitLab's old built-in agent pull-based gitops.manifest_projects feature was removed in GitLab 17.0. Current GitLab guidance uses the CNCF Flux project for reconciliation and the GitLab Agent for access management, integration, and cluster visibility.

flowchart TD
  DEV[Developer] --> APP[Application repo]
  APP -->|build immutable image| REG[OCI registry]
  APP -->|update desired digest| MAN[Deployment repo]
  MAN --> FLUX[Flux source/reconcile]
  FLUX --> K8S[Kubernetes cluster]
  AG[GitLab Agent] <-->|KAS connection| GL[GitLab]
  AG -->|cluster state / access bridge| K8S
  K8S -->|observed state| FLUX
  GL -.environment / dashboard evidence.-> AG

Flux, not GitLab CI, performs the repeated convergence loop. The Agent is still useful: it connects the cluster to GitLab, helps bootstrap/visualize integrations, and supports access. This course teaches that integration boundary; the dedicated Argo CD/GitOps course remains the place for deeper GitOps-controller design.

6. Environment identity is evidence, not convergence proof

A GitLab deployment job can create an environment/deployment record that ties a Git ref and job to a named environment. Kubernetes may later drift, a controller may fail to reconcile, or a human may mutate the cluster directly. Therefore a production evidence chain should include the GitLab deployment SHA, immutable image digest, declared manifest revision, and independently observed Kubernetes workload identity.

7. Read-only inspection before any change

On GitLab, start with Operate → Kubernetes clusters and inspect registered agents, connection state, configuration location, and token metadata. Through the Free REST API, Developer/Maintainer/Owner can list and retrieve agents; creating/deleting an agent requires Maintainer/Owner. List token metadata without printing token values.

# Example read-only API shapes; use your authenticated glab session or a narrowly scoped token.
glab api projects/:id/cluster_agents | jq '.[] | {id,name,created_at,config_project:.config_project.path_with_namespace}'
glab api projects/:id/cluster_agents/:agent_id/tokens | jq '.[] | {id,name,status,last_used_at}'
# Never print KUBECONFIG or an agent token.

Inside an optional disposable cluster, inspect identity before mutating anything: kubectl auth can-i is safer than attempting a destructive request first.

Knowledge check

8. Summary and next bridge

You now have the core trust model: GitLab authorizes use of an agent connection, KAS and agentk transport the request, and Kubernetes authorizes the resulting identity. The next lesson turns that model into a reproducible fixture workflow and an optional local-cluster exercise without exposing production credentials.

Primary sources and version notes

These lessons were finalized against current official GitLab documentation on 2026-08-22. Kubernetes, Flux, agentk, glab, KAS, and cluster security evolve independently, so re-check current GitLab version/tier, supported agent/Kubernetes versions, CLI syntax, and cluster policy before production use.

• GitLab 19.3 release
• Connecting a Kubernetes cluster with GitLab
• Install the GitLab Agent for Kubernetes
• Using GitLab CI/CD with a Kubernetes cluster
• Grant users Kubernetes access
• Using GitOps with a Kubernetes cluster
• Migrate legacy agent GitOps to Flux
• Managing agent instances and tokens
• Kubernetes Agent REST API
• Kubernetes managed resources and environments
• GitLab deprecations and removals
• GitLab token security overview