kubectl Advanced Cheat Sheet
Power-user reference for kubectl. Covers JSONPath queries, custom output, debugging workflows, resource management, and rollout strategies.
Basics: Kubernetes Cheat Sheet | Deep dive: Kubernetes Production Checklist
JSONPath Queries
kubectl supports JSONPath expressions with -o jsonpath='{...}'.
Syntax Basics
| Expression | Description |
|---|---|
{.metadata.name} | Single field |
{.items[*].metadata.name} | Array field from all items |
{.items[0].metadata.name} | First item only |
{.items[?(@.status.phase=="Running")].metadata.name} | Filter by condition |
{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end} | Range loop with formatting |
Practical Examples
# Get all pod IPs
kubectl get pods -o jsonpath='{.items[*].status.podIP}'
# Pod name and node, tab-separated
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.nodeName}{"\n"}{end}'
# Get all container images running in a namespace
kubectl get pods -o jsonpath='{.items[*].spec.containers[*].image}' | tr ' ' '\n' | sort -u
# Get all nodes and their allocatable CPU
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.allocatable.cpu}{"\n"}{end}'
# Get pods in CrashLoopBackOff
kubectl get pods -o jsonpath='{.items[?(@.status.containerStatuses[0].state.waiting.reason=="CrashLoopBackOff")].metadata.name}'
# Get all PVCs and their bound PV names
kubectl get pvc -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.volumeName}{"\t"}{.status.phase}{"\n"}{end}'
Custom Columns
More readable than JSONPath for tabular output.
# Basic custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,IP:.status.podIP,NODE:.spec.nodeName
# With restarts count
kubectl get pods -o custom-columns=\
NAME:.metadata.name,\
READY:.status.containerStatuses[0].ready,\
RESTARTS:.status.containerStatuses[0].restartCount,\
AGE:.metadata.creationTimestamp
# Node resource summary
kubectl get nodes -o custom-columns=\
NAME:.metadata.name,\
CPU:.status.allocatable.cpu,\
MEMORY:.status.allocatable.memory,\
PODS:.status.allocatable.pods
# Service endpoints (v1 Endpoints is deprecated since K8s 1.33; kubectl prints a warning)
kubectl get endpoints -o custom-columns=\
SERVICE:.metadata.name,\
ENDPOINTS:.subsets[*].addresses[*].ip
# Same via EndpointSlices (the current API)
kubectl get endpointslices -o custom-columns=\
SERVICE:.metadata.labels.kubernetes\.io/service-name,\
ENDPOINTS:.endpoints[*].addresses[*]
TIP
Save custom column definitions to a file and reuse with -o custom-columns-file=columns.txt.
Other Output Tricks
| Command | Description |
|---|---|
kubectl get pods --sort-by=.status.startTime | Sort by any JSONPath field |
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount' | Sort by restart count |
kubectl get pods -o name | pod/name lines, ideal for piping to xargs |
kubectl get pods -o jsonpath-as-json='{.items[*].metadata.name}' | JSONPath result as a JSON array |
kubectl get deploy my-app -o yaml --show-managed-fields | Include managedFields (who owns which field) |
kubectl get --raw /readyz?verbose | Hit an API server endpoint directly |
kubectl explain deploy.spec.strategy --recursive | Field docs for any resource, from the live API |
kubectl get pods -w | Watch for changes |
kubectl get pods --chunk-size=500 | Page through very large lists |
# Go template output (handy for secrets: base64decode is built in)
kubectl get pods -o go-template='{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}'
kubectl get secret my-secret -o go-template='{{range $k, $v := .data}}{{$k}}={{$v | base64decode}}{{"\n"}}{{end}}'
# Decode a single secret key
kubectl get secret my-secret -o jsonpath='{.data.password}' | base64 -d
Debugging Pods
Interactive Debug Containers
# Ephemeral debug container (beta in 1.23, GA in 1.25)
kubectl debug -it pod-name --image=busybox --target=app-container
# Debug with full networking tools
kubectl debug -it pod-name --image=nicolaka/netshoot --target=app-container
# Debug by copying the pod (non-destructive)
kubectl debug pod-name -it --copy-to=debug-pod --container=debug --image=busybox
# Copy the pod but swap the app image (e.g. a distroless image for one with a shell)
kubectl debug pod-name -it --copy-to=debug-pod --set-image=app=myimg:debug
# Copy the pod and override the command of a crashing container
kubectl debug pod-name -it --copy-to=debug-pod --container=app -- sh
# Copy the pod and share process namespace so you can see the app's processes
kubectl debug pod-name -it --copy-to=debug-pod --image=busybox --share-processes
# Debug a node (host filesystem mounted at /host; chroot /host for a host shell)
kubectl debug node/node-name -it --image=busybox
# Security profiles: legacy (default), general, baseline, restricted, netadmin, sysadmin
kubectl debug -it pod-name --image=nicolaka/netshoot --target=app --profile=netadmin
kubectl debug node/node-name -it --image=ubuntu --profile=sysadmin
# Clean up copies when done (ephemeral containers cannot be removed; they leave with the pod)
kubectl delete pod debug-pod
| Flag | What it does |
|---|---|
--target=CONTAINER | Share that container's process namespace (see its PIDs, /proc/1/root) |
--copy-to=NAME | Debug a copy of the pod instead of the original |
--set-image=c=img | In the copy, replace container images (*=img for all) |
--share-processes | In the copy, enable a shared process namespace |
--profile=... | Apply a predefined security context to the debug container |
--custom=file.yaml | Merge a partial container spec (env, volume mounts, securityContext) into the debug container |
TIP
--target only works when the runtime supports process namespace targeting (containerd and CRI-O do). Without it you see the debug container's own processes only.
Diagnosing Pod Issues
# Full event history for a pod
kubectl describe pod pod-name | grep -A 20 Events
# Events for one object, sorted by time (kubectl events is GA since 1.28)
kubectl events --for pod/pod-name
kubectl events --for deploy/my-app --watch
kubectl events -A --types=Warning
# Wait for a condition instead of polling
kubectl wait --for=condition=Ready pod -l app=web --timeout=120s
kubectl wait --for=condition=complete job/migrate --timeout=10m
kubectl wait --for=delete pod/pod-name --timeout=60s
kubectl wait --for=jsonpath='{.status.phase}'=Running pod/pod-name
# Check why a pod is pending
kubectl get pod pod-name -o jsonpath='{.status.conditions[?(@.type=="PodScheduled")]}'
# Check OOMKilled
kubectl get pod pod-name -o jsonpath='{.status.containerStatuses[*].lastState.terminated.reason}'
# Get previous container logs (after crash)
kubectl logs pod-name --previous
# Get logs from all containers in a pod
kubectl logs pod-name --all-containers
# Stream logs with timestamps
kubectl logs -f pod-name --timestamps
# Get logs from the last hour
kubectl logs pod-name --since=1h
# Get logs matching a pattern
kubectl logs pod-name | grep -i error
# Logs from every pod of a deployment / label (default max 5 concurrent streams)
kubectl logs deploy/my-app --all-containers --prefix
kubectl logs -l app=web -f --max-log-requests=20 --prefix
# Last 100 lines only
kubectl logs pod-name --tail=100
# Copy files out of / into a pod (needs tar in the container)
kubectl cp my-ns/pod-name:/var/log/app.log ./app.log -c app
kubectl cp ./config.json my-ns/pod-name:/tmp/config.json
Network Debugging
# Port-forward to a pod
kubectl port-forward pod/pod-name 8080:80
# Port-forward to a service
kubectl port-forward svc/my-service 8080:80
# Port-forward to a deployment (picks a pod)
kubectl port-forward deploy/my-app 8080:80
# Listen on all interfaces, not just localhost
kubectl port-forward --address 0.0.0.0 svc/my-service 8080:80
# Check DNS resolution from inside a pod
kubectl exec -it pod-name -- nslookup my-service.default.svc.cluster.local
# Test connectivity between pods
kubectl exec -it pod-name -- wget -qO- http://other-service:8080/health
# Check network policies affecting a pod
kubectl get networkpolicy -o wide
# Which pods back a Service right now
kubectl get endpointslices -l kubernetes.io/service-name=my-service
# Throwaway debug pod in the cluster network
kubectl run tmp --rm -it --restart=Never --image=nicolaka/netshoot -- bash
Apply, Diff & Server-Side Apply
# Preview what apply would change (exit code 1 = differences found)
kubectl diff -f manifest.yaml
kubectl diff -k overlays/prod/
# Server-side apply: the API server merges and tracks field ownership
kubectl apply --server-side -f manifest.yaml
# Named field manager (use the same name every time from CI)
kubectl apply --server-side --field-manager=ci-pipeline -f manifest.yaml
# Take ownership of fields another manager owns (resolves conflict errors)
kubectl apply --server-side --force-conflicts -f manifest.yaml
# Validate without persisting
kubectl apply -f manifest.yaml --dry-run=server
kubectl apply -f manifest.yaml --dry-run=client -o yaml
# Generate a manifest skeleton
kubectl create deployment web --image=nginx:1.27 --replicas=3 --dry-run=client -o yaml > web.yaml
# Ask before deleting (shows what will go, then prompts)
kubectl delete -f manifest.yaml --interactive
| Client-side apply | Server-side apply |
|---|---|
Stores kubectl.kubernetes.io/last-applied-configuration annotation | Tracks ownership in metadata.managedFields |
| Merge computed by kubectl | Merge computed by the API server |
| Silently overwrites fields others changed | Raises a conflict unless you pass --force-conflicts |
| Annotation size limit (256 KiB) breaks huge objects (CRDs) | No annotation, so large objects work |
WARNING
Mixing client-side and server-side apply on the same object, or with different --field-manager names, causes confusing ownership conflicts. Pick one per object, and use a fixed manager name in automation.
Resource Management
Resource Quotas & Limits
# View resource usage per pod
kubectl top pods --sort-by=cpu
kubectl top pods --sort-by=memory
# View resource usage per node
kubectl top nodes
# View resource requests and limits
kubectl get pods -o custom-columns=\
NAME:.metadata.name,\
CPU_REQ:.spec.containers[0].resources.requests.cpu,\
CPU_LIM:.spec.containers[0].resources.limits.cpu,\
MEM_REQ:.spec.containers[0].resources.requests.memory,\
MEM_LIM:.spec.containers[0].resources.limits.memory
# Check quota usage in namespace
kubectl describe resourcequota -n my-namespace
# Check limit ranges
kubectl describe limitrange -n my-namespace
Labeling & Annotations
# Add label
kubectl label pod pod-name env=production
# Overwrite existing label
kubectl label pod pod-name env=staging --overwrite
# Remove label
kubectl label pod pod-name env-
# Add label to all pods
kubectl label pods --all release=v2
# Annotate a resource
kubectl annotate deployment my-app description="Main API"
# Filter by label
kubectl get pods -l 'env in (production,staging)'
kubectl get pods -l 'app=web,version!=v1'
Rollouts & Deployments
Rollout Management
| Command | Description |
|---|---|
kubectl rollout status deploy/my-app | Watch rollout progress |
kubectl rollout history deploy/my-app | View rollout history |
kubectl rollout history deploy/my-app --revision=3 | Details of a specific revision |
kubectl rollout undo deploy/my-app | Rollback to previous revision |
kubectl rollout undo deploy/my-app --to-revision=2 | Rollback to specific revision |
kubectl rollout pause deploy/my-app | Pause a rollout |
kubectl rollout resume deploy/my-app | Resume a paused rollout |
kubectl rollout restart deploy/my-app | Restart all pods (rolling) |
kubectl rollout status deploy/my-app --timeout=5m | Fail (non-zero exit) if not done in 5 min, useful in CI |
kubectl rollout status sts/db / ds/agent | Works for StatefulSets and DaemonSets too |
kubectl rollout undo sts/db | Undo works for StatefulSets and DaemonSets (via ControllerRevisions) |
kubectl annotate deploy/my-app kubernetes.io/change-cause="bump to v2" | Set the CHANGE-CAUSE shown in rollout history (--record is deprecated) |
kubectl set image deploy/my-app app=myimg:v2 | Change an image (triggers a rollout) |
kubectl set env deploy/my-app LOG_LEVEL=debug | Change env vars (triggers a rollout) |
kubectl set resources deploy/my-app -c app --limits=memory=512Mi | Change resources (triggers a rollout) |
TIP
rollout undo rolls back the pod template only. ConfigMaps and Secrets the pods reference are not versioned, so a rollback after a config change brings back the old image with the new config.
Scaling
# Scale deployment
kubectl scale deploy/my-app --replicas=5
# Scale only if current replicas match (guards against races)
kubectl scale deploy/my-app --current-replicas=3 --replicas=5
# Autoscale (HPA). --cpu replaces the older --cpu-percent flag
kubectl autoscale deploy/my-app --min=2 --max=10 --cpu=70%
kubectl autoscale deploy/my-app --min=2 --max=10 --cpu=70% --memory=80%
# Check HPA status
kubectl get hpa
# Describe HPA for details
kubectl describe hpa my-app
Canary with Labels
# Deploy canary alongside stable
kubectl set image deploy/my-app-canary app=myimg:v2
# Shift traffic by adjusting replicas
kubectl scale deploy/my-app-stable --replicas=9
kubectl scale deploy/my-app-canary --replicas=1
# Both behind same Service via shared label selector
# Service selects: app=my-app (both deployments have this label)
Bulk Operations
# Delete all evicted pods
kubectl get pods --field-selector=status.phase=Failed -o name | xargs kubectl delete
# Delete all completed jobs
kubectl delete jobs --field-selector status.successful=1
# Restart all deployments in a namespace
kubectl rollout restart deploy -n my-namespace
# Get all images across all namespaces
kubectl get pods -A -o jsonpath='{range .items[*]}{.spec.containers[*].image}{"\n"}{end}' | sort -u
# Export resources in a namespace (backup)
# Note: "all" covers only core workload types (pods, services, deployments, replicasets,
# statefulsets, daemonsets, jobs, cronjobs, HPAs). It skips ConfigMaps, Secrets, Ingresses,
# PVCs, RBAC and CRDs, so list them explicitly:
kubectl get all -n my-namespace -o yaml > namespace-backup.yaml
kubectl get deploy,sts,svc,ing,cm,secret,pvc,sa,role,rolebinding -n my-namespace -o yaml > ns-backup.yaml
# Everything namespaced, really (slow)
kubectl api-resources --verbs=list --namespaced -o name \
| xargs -n1 kubectl get -n my-namespace --ignore-not-found --show-kind -o name
# Drain a node for maintenance
kubectl drain node-name --ignore-daemonsets --delete-emptydir-data
# Uncordon node after maintenance
kubectl uncordon node-name
# Cordon node (no new pods, existing stay)
kubectl cordon node-name
# Drain with a timeout, respecting PodDisruptionBudgets
kubectl drain node-name --ignore-daemonsets --delete-emptydir-data --timeout=10m
# Remove a stuck finalizer (last resort: the controller's cleanup is skipped)
kubectl patch pvc my-pvc --type=merge -p '{"metadata":{"finalizers":null}}'
# Force-delete a pod stuck in Terminating (only when the node is truly gone)
kubectl delete pod pod-name --grace-period=0 --force
Patch Operations
# Strategic merge patch (adds/merges)
kubectl patch deploy my-app -p '{"spec":{"template":{"spec":{"containers":[{"name":"app","resources":{"limits":{"memory":"512Mi"}}}]}}}}'
# JSON merge patch
kubectl patch deploy my-app --type=merge -p '{"spec":{"replicas":3}}'
# JSON patch (precise operations)
kubectl patch deploy my-app --type=json -p='[{"op":"replace","path":"/spec/replicas","value":5}]'
# Patch to add a sidecar
kubectl patch deploy my-app --type=json -p='[{"op":"add","path":"/spec/template/spec/containers/-","value":{"name":"sidecar","image":"envoyproxy/envoy:latest"}}]'
# Remove a field: null in a merge / strategic merge patch deletes it
kubectl patch deploy my-app --type=merge -p '{"metadata":{"annotations":{"old-key":null}}}'
# JSON patch remove (note: "/" in keys is escaped as "~1")
kubectl patch deploy my-app --type=json -p='[{"op":"remove","path":"/metadata/annotations/example.com~1owner"}]'
# Patch from a file
kubectl patch deploy my-app --patch-file=patch.yaml
# Patch a subresource (scale or status; GA since 1.33)
kubectl patch deploy my-app --subresource=scale --type=merge -p '{"spec":{"replicas":3}}'
--type | Lists (e.g. containers) | Delete a field |
|---|---|---|
strategic (default) | Merged by key (name for containers) | Set to null, or $patch: delete |
merge (RFC 7386) | Replaced entirely | Set to null |
json (RFC 6902) | Indexed ops (/containers/0, /- to append) | {"op":"remove"} |
WARNING
Strategic merge patch works only on built-in types. CRDs accept merge and json patches only.
Context & Namespace Shortcuts
# Install kubectx/kubens for fast switching
# Switch context
kubectx staging
# Switch namespace
kubens kube-system
# Create alias for frequently used namespace
alias kp='kubectl -n production'
alias ks='kubectl -n staging'
# Set default namespace for current context
kubectl config set-context --current --namespace=production
# Show which namespace the current context uses
kubectl config view --minify -o jsonpath='{..namespace}'
# Merge kubeconfigs for one command / view them flattened
KUBECONFIG=~/.kube/config:~/.kube/staging kubectl config view --flatten > merged.yaml
# Run one command against another context without switching
kubectl --context=staging get pods
kuberc (user preferences)
~/.kube/kuberc (beta since kubectl 1.34) holds personal defaults and aliases, separate from kubeconfig:
apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
defaults:
- command: apply
options:
- name: server-side
default: "true"
- command: delete
options:
- name: interactive
default: "true"
aliases:
- name: getn
command: get
options:
- name: output
default: wide
Disable it with KUBERC=off (or --kuberc=off), or point elsewhere with --kuberc=path / KUBERC=path. Flags you pass explicitly always override kuberc defaults.
RBAC Debugging
# Check if you can perform an action
kubectl auth can-i create deployments
kubectl auth can-i delete pods --namespace production
# Check what a service account can do
kubectl auth can-i --list --as=system:serviceaccount:default:my-sa
# Check who can perform an action (not built in: krew plugin "who-can")
kubectl krew install who-can
kubectl who-can create pods -n production
# Who am I, as the API server sees me (GA since 1.28)
kubectl auth whoami
# Impersonate a user or group for any command
kubectl get pods --as=jane --as-group=developers
# Short-lived token for a service account (TokenRequest API)
kubectl create token my-sa --duration=1h
# View cluster roles
kubectl get clusterroles | grep -v system:
# View role bindings
kubectl get rolebindings -n my-namespace -o wide
WARNING
kubectl auth can-i checks RBAC permissions but does not account for admission controllers, which may still deny the request.
Useful Aliases
# Add to ~/.bashrc or ~/.zshrc
alias k='kubectl'
alias kgp='kubectl get pods'
alias kgs='kubectl get svc'
alias kgd='kubectl get deploy'
alias kgn='kubectl get nodes'
alias kdp='kubectl describe pod'
alias kl='kubectl logs'
alias klf='kubectl logs -f'
alias kex='kubectl exec -it'
alias kaf='kubectl apply -f'
alias kdf='kubectl delete -f'
# Completion
source <(kubectl completion bash) # bash
source <(kubectl completion zsh) # zsh
complete -o default -F __start_kubectl k # alias completion (bash)
compdef k=kubectl # alias completion (zsh, after the source line)
Plugins (krew)
kubectl krew install ctx ns neat tree stern who-can
kubectl plugin list
| Plugin | What it does |
|---|---|
ctx / ns | kubectx / kubens as kubectl subcommands |
neat | Strip status, managedFields and defaults from YAML output |
tree | Show ownership tree (Deployment → ReplicaSet → Pod) |
stern | Tail logs from many pods with colour per pod |
who-can | Reverse RBAC lookup |
Test Yourself
-
What JSONPath expression filters pods in CrashLoopBackOff?
{.items[?(@.status.containerStatuses[0].state.waiting.reason=="CrashLoopBackOff")].metadata.name} -
How do you launch an ephemeral debug container attached to an existing pod?
kubectl debug -it pod-name --image=busybox --target=app-container -
What command checks if your service account can create deployments?
kubectl auth can-i create deployments -
How do you view resource requests and limits for all pods with custom columns?
kubectl get pods -o custom-columns=NAME:.metadata.name,CPU_REQ:.spec.containers[0].resources.requests.cpu,... -
What command drains a node for maintenance?
kubectl drain node-name --ignore-daemonsets --delete-emptydir-data -
How do you delete all evicted/failed pods in one command?
kubectl get pods --field-selector=status.phase=Failed -o name | xargs kubectl delete -
What patch type allows precise JSON operations like add/replace/remove?
--type=json(JSON Patch) -
How do you see the details of a specific rollout revision?
kubectl rollout history deploy/my-app --revision=3 -
What command checks what the last OOMKilled reason was for a pod?
kubectl get pod pod-name -o jsonpath='{.status.containerStatuses[*].lastState.terminated.reason}' -
How do you make the
kalias work with kubectl tab completion?complete -o default -F __start_kubectl k
Common Gotchas
kubectl auth can-idoes not check admission controllers. RBAC may allow an action, but a webhook admission controller can still deny it. Do not rely solely oncan-ifor security auditing.kubectl drainwithout--ignore-daemonsetsrefuses to start. It errors out with "cannot delete DaemonSet-managed Pods", because the DaemonSet controller would recreate them anyway. Always include this flag. A drain that hangs is usually a PodDisruptionBudget blocking eviction.- Removing fields with patches. In a strategic merge or JSON merge patch, set the field to
nullto delete it; in a JSON patch use{"op": "remove", "path": "/spec/..."}. Merge patches replace whole lists, so patchingcontainerswith--type=mergedrops every container you did not list. kubectl delete podwithout understanding restarts. If a Deployment manages the pod, Kubernetes immediately creates a replacement. Delete the Deployment or scale to 0 instead.kubectl get allis not "all". It skips ConfigMaps, Secrets, Ingresses, PVCs, RBAC objects and custom resources.kubectl logs -lshows only 10 lines per pod and 5 pods at a time. With a selector,--taildefaults to 10; raise it with--tail=-1and--max-log-requests.- Ephemeral containers are permanent for the pod's life. You cannot remove or restart one; each
kubectl debugadds another. Use--copy-toon busy production pods. --force --grace-period=0does not stop the container. It only removes the API object. If the node is still alive, the old process can keep running alongside the replacement (dangerous for StatefulSets).
One-Liner Summary
Advanced kubectl is about JSONPath queries, ephemeral debug containers, custom columns, and bulk operations -- master these to debug and manage production Kubernetes clusters efficiently.
Last updated: 2026-11-09