Onboard AI Agents as a Platform Persona: RBAC, Quotas, and Audit

Tier: Advanced · Hands-on time: ~90 minutes

The 2026 platform consensus is that agents become a first-class platform persona: their own identities, scoped RBAC, quotas, egress rules, and audit trails, provisioned through golden paths like any other workload. This playbook builds that persona for your first two agent workloads, so "an agent did something weird" is a queryable fact instead of a forensic mystery.

When to use

• •
  Engineers are running coding agents (Claude Code/Copilot-class) or ops agents (K8sGPT/HolmesGPT-class) against org systems with personal tokens.
• •
  You are about to grant an AI tool standing access to clusters, repos, or internal APIs.
• •
  Platform strategy work: defining what "AI-ready platform" means concretely for your org, beyond a slide.

Skip the ceremony for a purely local agent touching nothing shared — the persona starts mattering the moment shared systems, credentials, or spend are involved.

Prerequisites

• •
  An inventory candidate list of agent workloads in play (ask teams — you will find more than you expect).
• •
  Ability to mint non-human identities: K8s ServiceAccounts, cloud IAM roles, Git provider machine users/apps, OIDC workload identity.
• •
  Policy tooling for K8s if applicable (Kyverno or OPA/Gatekeeper) and NetworkPolicy support.
• •
  Your platform's normal observability stack — agent activity becomes ordinary telemetry with an extra label.

The workflow

1. 1.

   Inventory and classify what is already running. For each agent workload: what it reads, what it can write, whose credentials it uses today, and its blast radius if prompt-injected. Classify into tiers: read-only, propose-only (writes PRs/plans, humans apply), and act-with-approval. Fully autonomous write access is not a starting tier for anything.

2. 2.

   Mint identities — one per agent workload, never shared. Pattern: a dedicated ServiceAccount / IAM role / Git machine-user per agent use case (e.g., agent-ci-reviewer, agent-incident-investigator), bound via OIDC/workload identity where possible so there are no long-lived secrets to leak. Naming convention matters: agent-* prefixes make every downstream log, policy, and dashboard filterable in one grep.

3. 3.

   Scope permissions to the tier, mechanically. Read-only tier gets read-only roles (and NOT cluster-wide: namespace-scoped, resource-enumerated). Propose-only gets write access to branches/PRs but no merge, plan but no apply. Act-with-approval gets execution rights only through the approval-gated pipeline (pb-37 pattern). Have AI draft the Role/ClusterRole/IAM JSON from your tier descriptions — then review every verb; models over-grant reflexively (* verbs, list secrets) because permissive YAML "works".

4. 4.

   Add the quota and egress walls. Per agent identity: K8s ResourceQuota/LimitRange on any namespace it can schedule into; API rate limits at your gateway; LLM token budgets via gateway virtual keys (pb-30); NetworkPolicy/egress rules so an agent that reads internal docs cannot also POST to arbitrary external hosts. Egress control is your strongest structural defense against prompt-injection exfiltration — an injected agent that cannot reach out cannot leak out.

5. 5.

   Enforce the persona with policy-as-code. Kyverno/OPA rules that make the paved road mandatory: workloads labeled persona=agent must run with an agent-* ServiceAccount, must carry an owner annotation, must have a NetworkPolicy, cannot mount secrets outside an allowlist, cannot run in privileged mode. Now "agents follow the rules" is admission control, not a wiki page.

6. 6.

   Make audit a first-class output. Route all agent-identity activity (K8s audit log, cloud CloudTrail-class logs, Git audit, gateway logs) into your SIEM/log stack keyed on the agent-* identities. Build the two dashboards that matter: "what did agent X do in the last 24h" and "which agent identities are approaching quota/budget". Add alerts for out-of-pattern behavior: an agent identity touching a resource class it never touched before, auth failures (scope-probing), or egress denials.

7. 7.

   Package it as a golden path. Turn steps 2–6 into a template (pb-35): a team requesting "agent access" gets identity + scoped role + quotas + egress policy + dashboards by filling five parameters, with tier upgrades requiring platform review. Onboarding the third agent should take minutes.

Tool variants

• Kubernetes-centric: ServiceAccounts + RBAC + Kyverno + NetworkPolicy + ResourceQuota, as above; kind/minikube reproduces the full pattern for a ₹0 lab.
• Cloud IAM-centric: dedicated roles with permission boundaries (AWS) / custom roles (GCP/Azure), workload identity federation instead of static keys, and CloudTrail-class filtering on the agent principals.
• Git provider: GitHub Apps (not PATs) per agent with fine-grained repo permissions and their own audit stream; branch protection ensures propose-only stays propose-only.
• Gateway layer: LiteLLM/Portkey virtual keys as the agent's LLM identity — budgets, model allowlists, and logging per agent workload (composes with pb-30).

Verification

• •
  Negative tests per tier: the read-only agent's token fails a write; the propose-only agent cannot merge or apply; the act-tier agent's action without approval is blocked. Run these as scheduled probes, not one-time checks.
• •
  Admission control proven: a persona=agent pod with a human ServiceAccount or missing NetworkPolicy is rejected.
• •
  Audit drill: for a chosen agent action, reconstruct actor, trigger, permissions used, and effects from logs in under 10 minutes.
• •
  Egress test: agent namespace cannot reach a canary external endpoint; denial appears in logs/alerts.
• •
  Revocation drill: one identity disabled in under 5 minutes, affecting only that agent workload.

Pitfalls

• Shared "AI service account". One identity for all agents recreates the borrowed-credentials problem with extra steps — per-workload identity or the audit story collapses.
• Accepting AI-drafted RBAC unreviewed. Over-granted roles are the top failure of generated policy; review verbs and resource lists line by line, and test with the negative probes.
• Quotas without budgets (or vice versa). Compute quota caps runaway pods; token budgets cap runaway spend; an agent loop needs both walls.
• Standing long-lived keys. Static tokens in agent configs leak like all static tokens; OIDC/workload identity plus short TTLs, or at minimum scheduled rotation via pb-33 runbooks.
• Granting the autonomy tier on request. Tier upgrades are earned with incident-free history and reviewed scopes — "the demo worked" is not a control.

Restricted-environment variant

• •
  Client estates: agent identities must be created under the client's IAM governance and named per their convention; the tier model maps cleanly onto MSA language ("read-only advisory tooling" vs "change-executing automation"), which makes client sign-off concrete rather than hand-wavy.
• •
  Keep agent audit logs in the client boundary and reportable — several clients now ask "what can your AI tooling touch?"; this playbook's persona inventory IS that answer.
• •
  Self-hosted agents (Ollama/vLLM-backed) still get the full persona: local models remove the data-egress concern, not the blast-radius one.

Success criteria

• •
  Zero agent workloads on human credentials in the covered scope; every agent action attributable to an agent-* identity in one log query.
• •
  Negative-probe suite green on schedule; at least one real over-grant caught and tightened in review.
• •
  Agent onboarding via golden path in minutes, with tier upgrades gated by platform review.
• •
  You can answer "what did our agents do yesterday, and what could they have done?" with dashboards, not interviews.