Kubernetes Agent, Cluster Access, GitOps-Oriented Delivery, Kubernetes Deployments, and Environment Integration: Concepts, Architecture, and Mental Model

1. The practical problem: “the deploy job is green” tells you too little

Chapter 27 replaced long-lived provider secrets with explicit workload identity. Kubernetes adds another authorization and state boundary. A GitLab job can succeed while using the wrong cluster context, an Agent can be reachable while Kubernetes RBAC denies the operation, a manifest can apply successfully while Pods never become Ready, and GitLab can record a deployment while the external service remains unhealthy.

The chapter therefore treats Kubernetes delivery as a chain of independently inspectable states. The artifact has an immutable identity. The pipeline has an exact source and compiled configuration. The job is authorized to a specific Agent/context. Kubernetes authorizes only the required namespace operations. The desired manifest names the exact image digest. GitLab records the environment/deployment. Finally, the cluster’s rollout and service behavior are verified independently.

2. Mental model: seven identities cross two control planes

The flow begins with a verified artifact, not “whatever latest means now.” GitLab compiles a job for an exact SHA. Agent authorization exposes one or more named kube contexts to that job. The selected context reaches the cluster, where Kubernetes RBAC independently decides which namespace operations are allowed. The job either applies desired state directly, or a GitOps controller such as Flux reconciles reviewed desired state. GitLab then records an environment/deployment, while Kubernetes runtime state supplies the final health evidence.

The Agent is not a replacement for Kubernetes RBAC, and a GitLab environment is not the Kubernetes controller. These arrows are causal boundaries, not decorative boxes.

3. Name every state before changing any of it

4. What the GitLab Agent changes—and what it does not

The Agent opens an outbound connection from the cluster to GitLab’s Kubernetes Agent Server (KAS). In the CI/CD workflow, an authorized project’s jobs receive a kubeconfig containing contexts for Agent connections they may use. Runners do not need to run inside the target cluster.

Authorization is configured in the Agent project, for example:

# .gitlab/agents/staging-agent/config.yaml
ci_access:
  projects:
    - id: platform/example-app
      environments:
        - staging
        - review/*

This authorizes the project/environment combinations to receive the Agent context. Kubernetes permissions still come from the Agent service account or, where configured, impersonation plus RBAC.

5. Read-only inspection first

Before a deployment, establish the pipeline identity and the contexts visible to the job without dumping kubeconfig contents or credentials.

printf 'source=%s sha=%s pipeline=%s job=%s\n'   "$CI_PIPELINE_SOURCE" "$CI_COMMIT_SHA" "$CI_PIPELINE_ID" "$CI_JOB_ID"
kubectl config get-contexts -o name
kubectl config current-context
kubectl auth can-i get deployments -n glci-ch28
kubectl auth can-i create deployments -n glci-ch28
kubectl get namespace glci-ch28 --ignore-not-found
kubectl -n glci-ch28 get deployment,service,pod --ignore-not-found

Do not print $KUBECONFIG or its file contents. The safe evidence is the selected context name, authorization answers, cluster/namespace identity and resource metadata.

6. Context identity is part of deployment identity

With the Agent CI/CD workflow, the context name identifies the Agent configuration project and Agent. A production pipeline should select it explicitly rather than rely on whichever context happens to be current.

deploy_staging:
  stage: deploy
  variables:
    KUBE_CONTEXT: platform/cluster-agents:staging-agent
  before_script:
    - kubectl config use-context "$KUBE_CONTEXT"
  script:
    - kubectl auth can-i patch deployments -n app-staging
    - kubectl apply -f k8s/staging.yaml
    - kubectl rollout status deployment/example -n app-staging --timeout=180s

A context selection is evidence of where the request was sent. It is not evidence that RBAC allowed the change or that the rollout became healthy.

7. Least privilege lives in Kubernetes too

A common mistake is to install the Agent with a service account that can administer the whole cluster and then rely only on GitLab project authorization. That leaves one control plane doing work that should be shared with Kubernetes. Prefer namespace-scoped Roles and RoleBindings that permit only the API groups/resources/verbs the deployment job requires.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: glci-deployer
  namespace: app-staging
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch", "create", "update", "patch"]
  - apiGroups: [""]
    resources: ["pods", "services"]
    verbs: ["get", "list", "watch", "create", "update", "patch"]

Deletion rights, Secret access and cluster-scoped resources should be added only when a concrete workflow requires them.

8. Promote bytes, not a mutable tag

A Kubernetes manifest that says image: registry.example/app:latest does not uniquely identify deployed bytes. A release promotion should carry forward the already-tested digest:

spec:
  template:
    spec:
      containers:
        - name: app
          image: registry.example.test/platform/app@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

The digest links Chapters 23–26 to Kubernetes runtime state. After rollout, capture the Pod imageID and compare its digest to the intended manifest digest. A tag may still be retained as human-readable metadata, but it must not be the only production identity.

9. Push-based CI/CD and GitOps solve different control problems

GitLab’s legacy built-in Agent pull-based GitOps functionality is gone; current GitLab guidance is to use Flux for GitOps. The Agent remains valuable for connectivity, dashboard visibility and other integration features.

10. Environment integration records intent; the dashboard adds observation

A deployment job can associate the environment with an Agent and Kubernetes namespace using current YAML:

deploy_staging:
  stage: deploy
  script:
    - ./deploy-staging.sh
  environment:
    name: staging
    url: https://staging.example.test
    kubernetes:
      agent: platform/cluster-agents:staging-agent
      dashboard:
        namespace: app-staging

The environment/deployment record is GitLab-owned state. The Kubernetes dashboard can surface cluster resources, but operational acceptance still needs workload-specific health evidence. The older form with namespace directly under kubernetes: is deprecated; use dashboard: namespace:.

11. Rollout health is independent evidence

kubectl -n app-staging rollout status deployment/example --timeout=180s
kubectl -n app-staging get deployment/example -o json
kubectl -n app-staging get pods -l app=example   -o jsonpath='{range .items[*]}{.metadata.name}{"  "}{.status.phase}{"  "}{.status.containerStatuses[0].imageID}{"\n"}{end}'
kubectl -n app-staging get service/example -o json

“Deployment available replicas equal desired replicas,” “Pod Ready,” “container imageID matches the intended digest,” and “the service answers its health endpoint” are different observations. Preserve whichever are required by the service SLO.

12. Avoid deprecated connection mental models

Certificate-based cluster integration was deprecated in GitLab 14.5. Do not build new labs around project/group/instance certificate clusters or legacy “GitLab-managed cluster” assumptions. For current connectivity, use the Agent. For GitOps, use Flux. For a purely local lab, use a disposable kubeconfig only inside the local machine and clearly label it as a simulation—not as the recommended GitLab production pattern.

13. A read-only evidence checklist

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. Current GitLab documentation lists the Agent CI/CD workflow as Free, Premium, and Ultimate on GitLab.com, Self-Managed, and Dedicated. Authorized CI/CD jobs receive a KUBECONFIG containing contexts for authorized agent connections; the context identifies the agent configuration project and agent name. ci_access can authorize projects/groups and can restrict access to named environment patterns. The current per-agent authorization limit is 500 projects and 500 groups. CI-job impersonation with access_as: ci_job is Premium/Ultimate; the mandatory lab therefore demonstrates true Kubernetes namespace-scoped ServiceAccount RBAC locally instead of pretending that paid impersonation is Free. GitLab recommends Flux for GitOps; the Agent’s legacy built-in pull-based GitOps functionality was removed in GitLab 17.0. Certificate-based cluster integration was deprecated in GitLab 14.5. The Kubernetes dashboard is currently Beta and available on all tiers. For environment:kubernetes, dashboard namespace/Flux resource settings belong under dashboard:; the older direct namespace/flux_resource_path form is deprecated. Current GitLab Agent docs also note that authorization changes can take a short period to propagate. Preserve the before/after authorization evidence instead of blindly rerunning a denied deployment.

• Using GitLab CI/CD with a Kubernetes cluster — official reference.
• GitLab Agent for Kubernetes — official reference.
• Get started connecting a Kubernetes cluster — official reference.
• Install the Agent for Kubernetes — official reference.
• Migrate legacy Agent GitOps to Flux — official reference.
• Dashboard for Kubernetes — official reference.
• CI/CD YAML syntax — environment:kubernetes — official reference.
• Deprecated CI/CD keywords — official reference.
• Migrate from certificate-based Kubernetes integration — official reference.
• GitLab-managed Kubernetes resources — official reference.
• Kubernetes RBAC authorization — official reference.
• Kubernetes Deployments — official reference.
• kind quick start — official reference.
• Flux documentation — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.