Quick Start¶

After installing, run your first audit:

kubectl audit pods

kubectl audit pods demo

Choose the right subcommand¶

I want to…	Command
See all unhealthy pods	`kubectl audit pods -A`
Drill into a specific pod's containers	`kubectl audit containers -p <pod-name>`
Check which nodes can't schedule work	`kubectl audit nodes`
Find empty or stuck namespaces	`kubectl audit ns`
Find services with no backing pods	`kubectl audit svc -A`
Check deployment rollout health	`kubectl audit deploy -A`
Catch warning events cluster-wide	`kubectl audit events -A`
Check storage (PVC/PV) issues	`kubectl audit pvc -A && kubectl audit pv`

pods vs containers

kubectl audit pods — one row per pod, aggregate status
kubectl audit containers — one row per container, shows exact image/restart detail

Start with pods for a quick count. Use containers when you need to identify which container inside a multi-container pod is broken.

Common workflows¶

Incident triage — cluster-wide sweep¶

kubectl audit pods -A
kubectl audit nodes
kubectl audit ns
kubectl audit events -A

Pre-deploy smoke check¶

kubectl audit pods -n my-namespace
kubectl audit deploy -n my-namespace
kubectl audit svc -n my-namespace

Scope to a team namespace with label filter¶

kubectl audit pods -n team-a -l app=api
kubectl audit containers -n team-a -l app=api

Try a demo (no broken cluster needed)¶

Each audit type has a demo manifest that creates intentionally broken resources:

PodsServicesEvents

kubectl apply -f https://raw.githubusercontent.com/codenio/kubectl-audit/main/examples/audit-pods/demo.yaml
kubectl audit pods -n kubectl-audit-pods-demo
kubectl delete -f https://raw.githubusercontent.com/codenio/kubectl-audit/main/examples/audit-pods/demo.yaml

kubectl apply -f https://raw.githubusercontent.com/codenio/kubectl-audit/main/examples/audit-svc/demo.yaml
kubectl audit service -n kubectl-audit-svc-demo
kubectl delete -f https://raw.githubusercontent.com/codenio/kubectl-audit/main/examples/audit-svc/demo.yaml

kubectl apply -f https://raw.githubusercontent.com/codenio/kubectl-audit/main/examples/audit-events/demo.yaml
kubectl audit events -n kubectl-audit-events-demo
kubectl delete -f https://raw.githubusercontent.com/codenio/kubectl-audit/main/examples/audit-events/demo.yaml

See all demo examples →

Scripting and CI/CD¶

The audit summary is written to stderr, so stdout is clean for piping:

# Extract names of failing pods as JSON
kubectl audit pods -o json 2>/dev/null | jq '[.items[].metadata.name]'

# Non-zero exit if any unhealthy pods found
kubectl audit pods -n my-namespace -o name | grep -q . && echo "Issues found"

See the full CI/CD integration guide →

Next: RBAC & Permissions →