kubectl auth impersonate — acting as another identity

kubectl auth impersonate is the kubectl helper for setting the identity for subsequent commands. The operator runs kubectl auth impersonate once; the shell’s subsequent kubectl calls are treated as if they came from the impersonated identity. Impersonation is powerful — it is the closest Kubernetes has to sudo — but it is also a Critical control surface. A caller with the impersonate verb can act as any user, group, or SA in the cluster.

The basic syntax

# Substitute your own values before running:
AS_USER=alice
AS_GROUP=idp:oncall
AS_UID=a3f1c2e4-8b9d-4c7a-9f2e-1d6b5a4c3e2f

kubectl auth impersonate \
  --as "$AS_USER" \
  --as-group "$AS_GROUP" \
  --as-uid "$AS_UID"

The flags set the impersonated identity. They are stored in a shell environment (KUBECTL_AUTH_IMPERSONATE_*) that subsequent kubectl calls read.

# Impersonate alice
kubectl auth impersonate --as=alice

# Impersonate a member of the oncall group
kubectl auth impersonate --as=alice --as-group=idp:oncall

# Subsequent commands are as alice
kubectl get pods -n prod
# Treated as alice; RBAC applies to alice's identity

# Clear impersonation
kubectl auth impersonate --as="" --as-group=""
# Or unset the env vars
unset KUBECTL_AUTH_IMPERSONATE_USER

The audit log

The API server records the impersonation in the audit log:

{
  "user": {
    "username": "operator@example.com",
    "groups": ["idp:oncall"],
    "impersonatedUser": {
      "username": "alice",
      "groups": ["idp:dev"]
    }
  },
  "verb": "get",
  "resource": "pods",
  "namespace": "prod"
}

The user field shows the real identity (from TLS or token); the impersonatedUser shows the identity acted-as. An audit can distinguish “operator did something as alice” from “alice did something.” This is the right shape for forensic analysis.

flowchart LR
    A[Operator TLS cert] --> B[API server]
    C[Impersonation headers] --> B
    B --> D[impersonate verb check]
    D -->|allowed| E[Apply RBAC as impersonated]
    D -->|denied| F[403 cannot impersonate]
    B --> G[Audit log: real + impersonated]

Debugging RBAC issues

A user reports they cannot read a Secret in prod. The operator reproduces by impersonating:

# Reproduce the issue
kubectl auth impersonate --as=alice
kubectl get secret db-credentials -n prod
# Error from server (Forbidden):
#   secrets "db-credentials" is forbidden:
#   User "alice" cannot get resource "secrets" in API group "" in the namespace "prod"

# What can alice actually do?
kubectl auth can-i --list -n prod --as=alice
# (only the user's effective permissions)

# Clear impersonation
kubectl auth impersonate --as="" --as-group=""

The operator sees the exact 403 the user saw. The fix is to verify the user’s RBAC bindings and adjust.

Break-glass access

Impersonation is the canonical break-glass pattern. The on-call engineer authenticates with their OIDC identity (real, audited); the API server grants the impersonate verb on a break-glass SA; the engineer acts as the break-glass SA to perform the recovery:

# Operator authenticates as operator@example.com (real)
# The 'breakglass' group has the 'impersonate' verb on 'system:serviceaccounts:breakglass:admin'

# Impersonate the break-glass admin SA
kubectl auth impersonate \
  --as=system:serviceaccounts:breakglass:admin

# Perform the recovery
kubectl rollout undo deployment/api -n prod

# Clear impersonation
kubectl auth impersonate --as=""

The audit log records the real operator identity and the impersonated SA. The recovery is traceable to a human, not to an anonymous SA.

Security risks

Three risks of over-broad impersonation:

1. Operator can act as anyone. A binding of impersonate on users: * allows the operator to act as any user in the cluster, including system:anonymous (which is bound to nothing by default but is a foothold for evasion).
2. Operator can act as cluster-admin SAs. A binding of impersonate on serviceaccounts: kube-system: * allows the operator to act as kube-system SAs, including any SA with cluster-admin.
3. No record of impersonated actions. A misconfigured audit log that does not record impersonatedUser makes impersonation invisible. The fix is to ensure the audit policy records the impersonated identity.

Production failure modes

1. impersonate bound to a wildcard. An operator can act as anyone; an attacker who compromises the operator account is cluster-admin. The fix is to bind impersonate to specific users/groups/SAs.
2. Audit log not recording impersonation. The impersonated actions are invisible; forensic analysis cannot determine who actually performed them. The fix is an audit policy that records impersonatedUser.
3. Impersonation persists across sessions. A forgotten kubectl auth impersonate in a shell affects every subsequent command. The fix is to unset on shell exit, or to use --as per command instead of auth impersonate for the shell.
4. CI/CD uses impersonation to mask identity. The pipeline impersonates a SA that the audit log records, hiding the real operator. The fix is to require the pipeline to use its own SA, not to impersonate another.

Cross-course references

• The Observability course covers the audit log policies that record impersonation.
• The Linux course covers the sudo analogue that impersonation provides.

Quiz

Production discipline

kubectl auth impersonate is the most powerful primitive kubectl offers. A defensible RBAC programme binds impersonate to a small set of admin SAs (named, not wildcarded), records impersonatedUser in the audit log, and uses impersonation for debugging, break-glass, and testing — never for routine operations. The audit log is the proof: every impersonated action is traceable to a real identity. A cluster where impersonation is granted widely is a cluster where the audit log cannot be trusted; a cluster where impersonation is restricted and audited is a cluster where the audit log is the source of truth.