Read-Only kubectl Commands for AI Agents

---
name: read-only-kubernetes-audit-workflow
description: "Pin the context and namespace, use get, describe, logs, and auth checks, and reject mutating subcommands."
---

# Read-only Kubernetes audit

## Intended outcome

Explain cluster health and likely causes while keeping the audit technically read-only.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **kubectl** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
  - Install: `brew install kubectl`
  - Authentication: kubeconfig, service account token, exec credential plugin
  - Minimum permissions: Use a dedicated context and RBAC role limited to get, list, and watch for audit tasks.
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
  - Install: `brew install jq`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.

## Input contract

- Explicit kube context
- namespace scope
- read-only credentials
- audit question

## Output contract

- Resource inventory
- event and log evidence
- access check
- prioritized findings

## Safe workflow

1. **Confirm identity and scope** — Print the active context and verify allowed actions before reading workloads.
   - Input: Kubeconfig and target namespace
   - Output: Context, namespace, and permission boundary
   - Risk: `read-only`
   - Command: `kubectl config current-context && kubectl auth can-i --list -n example`
2. **Inspect resources** — Read workload status, recent events, descriptions, and bounded logs using structured output where practical.
   - Input: Confirmed context and namespace
   - Output: Resource, event, and log evidence
   - Risk: `read-only`
   - Command: `kubectl get pods -n example -o json`
3. **Summarize without remediation** — Rank findings and propose any mutation as a separate command with expected impact.
   - Input: Collected cluster evidence
   - Output: Audit report and optional remediation proposal
   - Risk: `read-only`

## Ask before proceeding

- Any apply, patch, edit, scale, rollout, delete, exec, or port-forward command
- Reading secrets or broadening namespaces
- Switching to a production context not supplied by the user

## Rollback

- No cluster rollback is required for the read-only path
- Remove temporary local output containing sensitive logs
- For approved changes, capture the existing resource manifest first

## Official sources

- [kubectl reference](https://kubernetes.io/docs/reference/kubectl/) — Official Kubernetes command reference for resource inspection and mutation.