Kubernetes Agent, GitOps Workflows, Cluster Access, Environments, and Deployment Integration: Configuration, Design Choices, and Tradeoffs

1. Agent connection versus stored kubeconfig

A stored kubeconfig puts long-lived cluster endpoint and credential material into GitLab CI/CD variables or another secret store. The Agent moves the connection model toward an in-cluster agent with an authenticated KAS channel and dynamically supplied contexts. That reduces direct credential distribution, especially for clusters behind NAT/firewalls, but it does not eliminate authorization design.

2. Flux reconciliation versus imperative CI deployment

An imperative CI job says “run these commands against the cluster now.” A GitOps controller says “this repository/OCI source declares desired state; keep the cluster converged to it.” The difference is operational, not cosmetic.

3. Shared cluster versus namespace or cluster isolation

A namespace is an administrative and naming boundary, not automatically a strong security boundary. Shared-cluster designs can be efficient, but cluster-scoped resources, controllers, network policy, admission policy, and node/runtime configuration can cross namespace boundaries. For sensitive environments, separate clusters or stronger tenancy controls may be justified.

4. Project authorization breadth is a platform architecture decision

Authorizing an individual project is easier to reason about than granting a whole group. A group authorization also extends to subgroup projects. Current GitLab supports environment filters on Free, which is a useful narrowing mechanism. Avoid granting “all projects” merely for convenience; instance-level authorization exists only on Self-Managed and is administrator-controlled.

ci_access:
  projects:
    - id: company/payments/deploy
      environments: [production]
  groups:
    - id: company/sandbox
      environments: [review/*]

The first line of defense is scope. The second is effective Kubernetes identity/RBAC. Premium/Ultimate impersonation improves that second layer, but even without it a dedicated low-privilege agent service account is safer than cluster-admin.

5. Service-account authority versus impersonation

On the Free basic CI workflow, requests inherit permissions from the service account used by agentk. If that service account is cluster-admin, every authorized job potentially inherits dangerous power. Premium/Ultimate CI job impersonation lets agentk present groups such as gitlab:ci_job, project IDs, and environment/tier groups to Kubernetes RBAC, enabling finer authorization.

6. Protected refs and runners are complementary controls, not substitutes for RBAC

Production access should consider source trust, runner trust, environment authorization, and cluster RBAC together. GitLab supports protected_branches_only for agent access on Self-Managed/Dedicated, but current documentation still carries a caution that the feature is for testing/not ready for production. Do not make it the only production boundary. On GitLab.com, use protected refs, environment filters, trusted runners, and Kubernetes-side controls appropriate to your tier.

7. Environment integration and GitLab-managed Kubernetes resources

GitLab can associate an environment job with an agent and, in newer workflows, manage environment Kubernetes resources through agent configuration. Treat this as a convenience/control plane, not an excuse to blur ownership. The manifest repository, environment template, agent configuration, and cluster RBAC should have explicit owners and review paths.

deploy_review:
  stage: deploy
  script:
    - echo "deployment action is intentionally synthetic"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    kubernetes:
      agent: company/platform/agent-config:lab-agent

8. Worked decision: a regulated API with review apps and production

Assume a 20-person team needs disposable review environments and a tightly controlled production cluster.

This design spends complexity where the blast radius is highest. It also keeps review-app convenience from silently becoming production authority.

Knowledge check

9. Summary and next bridge

The architecture decision is now explicit: use the Agent to avoid uncontrolled credential distribution, prefer Flux for production pull-based reconciliation, and make GitLab scope plus Kubernetes RBAC independently least-privilege. Lesson 4 practices diagnosing the failures that occur when one of those layers is broader, stale, or misinterpreted.

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