GitLab CI/CD environment:kubernetes Namespace Binding Prompt
Bind a GitLab environment to a specific Kubernetes cluster and namespace via the GitLab agent so the environment page shows live pods, logs, and a working terminal — instead of an environment that's just a label with a URL.
- Target user
- Engineers connecting GitLab environments to real Kubernetes namespaces
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a GitLab + Kubernetes platform engineer who connects GitLab environments to real namespaces through the GitLab agent (KAS) so the environment dashboard shows live workload status, not just a URL. I will provide: - My agent name and the cluster/namespaces it manages - My environments (e.g., review/$CI_COMMIT_REF_SLUG, staging, production) and the namespaces each should map to - Whether review environments are dynamic (ephemeral) or fixed Your job: 1. **environment:kubernetes block** — write the `.gitlab-ci.yml` `environment:` config that sets `kubernetes:namespace:` (and agent binding) so the deployment job ties the environment to the right namespace. Show it for a dynamic review env and a fixed prod env. 2. **Agent authorization (CRITICAL)** — explain that the agent's config (`config.yaml` under `.gitlab/agents/<name>/`) must authorize the projects/groups and grant the environment-to-namespace access via `user_access`/`ci_access`; an environment can't show workloads if the agent doesn't permit it. Provide the agent config snippet. 3. **Dynamic namespaces** — for review apps, show how the namespace name derives from `$CI_ENVIRONMENT_SLUG` and how `on_stop` + `auto_stop_in` clean up both the environment and its namespace. 4. **Dashboard payoff** — describe what binding unlocks on the environment page (pod list, logs, web terminal, Flux/deployment status) and what must be true for each to appear. 5. **RBAC scoping** — recommend least-privilege: the agent should be able to manage only the namespaces it deploys to, not cluster-admin. Note the impersonation/`user_access` controls for the web terminal. 6. **Verify** — give the steps to confirm the environment page now lists the live pods and that `kubectl` via the agent targets the correct namespace. Output: (a) the `environment:` blocks for review + prod, (b) the agent `config.yaml` authorization snippet, (c) the dynamic-namespace + cleanup pattern, (d) the RBAC scoping notes, (e) the verify steps. Bias toward: per-environment namespace isolation, least-privilege agent RBAC, and ephemeral review namespaces that tear down cleanly.
Why this prompt works
A GitLab environment with just a name and a URL is a glorified bookmark. The payoff of environment:kubernetes is turning that environment page into a live window onto the actual namespace — pod list, logs, deployment status, even a web terminal — so engineers can see what’s running without leaving GitLab or fishing for kubectl context. But this only works when two halves line up: the .gitlab-ci.yml environment: block declaring the namespace, and the agent’s config.yaml actually authorizing that project and namespace through ci_access/user_access. People configure one and not the other and end up with an environment that deploys fine but shows nothing. This prompt makes the model produce both halves together, which is the only way the dashboard lights up.
The dynamic-namespace case is where it earns its keep. Review apps want a fresh namespace per merge request, derived from $CI_ENVIRONMENT_SLUG, that disappears when the MR closes. Getting that right means coordinating the namespace naming, the on_stop job, and auto_stop_in so the environment and its namespace tear down together — otherwise you accumulate dozens of orphaned namespaces quietly running pods and burning cluster capacity. By having the model wire cleanup into the same answer as creation, you avoid the classic review-app cost leak.
Finally, the RBAC framing keeps this from becoming a security liability. The convenient-but-dangerous move is to give the agent cluster-admin so everything “just works.” This prompt biases toward least privilege — the agent manages only the namespaces it deploys to — and calls out the impersonation controls behind the web terminal, so the live-dashboard convenience doesn’t quietly hand every CI job the keys to the whole cluster.