On this page

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

ExpressionDescription
{.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

CommandDescription
kubectl get pods --sort-by=.status.startTimeSort by any JSONPath field
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'Sort by restart count
kubectl get pods -o namepod/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-fieldsInclude managedFields (who owns which field)
kubectl get --raw /readyz?verboseHit an API server endpoint directly
kubectl explain deploy.spec.strategy --recursiveField docs for any resource, from the live API
kubectl get pods -wWatch for changes
kubectl get pods --chunk-size=500Page 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
FlagWhat it does
--target=CONTAINERShare that container's process namespace (see its PIDs, /proc/1/root)
--copy-to=NAMEDebug a copy of the pod instead of the original
--set-image=c=imgIn the copy, replace container images (*=img for all)
--share-processesIn the copy, enable a shared process namespace
--profile=...Apply a predefined security context to the debug container
--custom=file.yamlMerge 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 applyServer-side apply
Stores kubectl.kubernetes.io/last-applied-configuration annotationTracks ownership in metadata.managedFields
Merge computed by kubectlMerge computed by the API server
Silently overwrites fields others changedRaises 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

CommandDescription
kubectl rollout status deploy/my-appWatch rollout progress
kubectl rollout history deploy/my-appView rollout history
kubectl rollout history deploy/my-app --revision=3Details of a specific revision
kubectl rollout undo deploy/my-appRollback to previous revision
kubectl rollout undo deploy/my-app --to-revision=2Rollback to specific revision
kubectl rollout pause deploy/my-appPause a rollout
kubectl rollout resume deploy/my-appResume a paused rollout
kubectl rollout restart deploy/my-appRestart all pods (rolling)
kubectl rollout status deploy/my-app --timeout=5mFail (non-zero exit) if not done in 5 min, useful in CI
kubectl rollout status sts/db / ds/agentWorks for StatefulSets and DaemonSets too
kubectl rollout undo sts/dbUndo 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:v2Change an image (triggers a rollout)
kubectl set env deploy/my-app LOG_LEVEL=debugChange env vars (triggers a rollout)
kubectl set resources deploy/my-app -c app --limits=memory=512MiChange 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}}'
--typeLists (e.g. containers)Delete a field
strategic (default)Merged by key (name for containers)Set to null, or $patch: delete
merge (RFC 7386)Replaced entirelySet 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
PluginWhat it does
ctx / nskubectx / kubens as kubectl subcommands
neatStrip status, managedFields and defaults from YAML output
treeShow ownership tree (Deployment → ReplicaSet → Pod)
sternTail logs from many pods with colour per pod
who-canReverse RBAC lookup

Test Yourself
  1. What JSONPath expression filters pods in CrashLoopBackOff? {.items[?(@.status.containerStatuses[0].state.waiting.reason=="CrashLoopBackOff")].metadata.name}

  2. How do you launch an ephemeral debug container attached to an existing pod? kubectl debug -it pod-name --image=busybox --target=app-container

  3. What command checks if your service account can create deployments? kubectl auth can-i create deployments

  4. 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,...

  5. What command drains a node for maintenance? kubectl drain node-name --ignore-daemonsets --delete-emptydir-data

  6. How do you delete all evicted/failed pods in one command? kubectl get pods --field-selector=status.phase=Failed -o name | xargs kubectl delete

  7. What patch type allows precise JSON operations like add/replace/remove? --type=json (JSON Patch)

  8. How do you see the details of a specific rollout revision? kubectl rollout history deploy/my-app --revision=3

  9. What command checks what the last OOMKilled reason was for a pod? kubectl get pod pod-name -o jsonpath='{.status.containerStatuses[*].lastState.terminated.reason}'

  10. How do you make the k alias work with kubectl tab completion? complete -o default -F __start_kubectl k

Common Gotchas

  • kubectl auth can-i does not check admission controllers. RBAC may allow an action, but a webhook admission controller can still deny it. Do not rely solely on can-i for security auditing.
  • kubectl drain without --ignore-daemonsets refuses 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 null to delete it; in a JSON patch use {"op": "remove", "path": "/spec/..."}. Merge patches replace whole lists, so patching containers with --type=merge drops every container you did not list.
  • kubectl delete pod without understanding restarts. If a Deployment manages the pod, Kubernetes immediately creates a replacement. Delete the Deployment or scale to 0 instead.
  • kubectl get all is not "all". It skips ConfigMaps, Secrets, Ingresses, PVCs, RBAC objects and custom resources.
  • kubectl logs -l shows only 10 lines per pod and 5 pods at a time. With a selector, --tail defaults to 10; raise it with --tail=-1 and --max-log-requests.
  • Ephemeral containers are permanent for the pod's life. You cannot remove or restart one; each kubectl debug adds another. Use --copy-to on busy production pods.
  • --force --grace-period=0 does 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