--- title: "kubectl" description: "kubectl is the command-line tool for talking to a Kubernetes cluster. Use it to deploy apps, inspect and manage resources, stream logs, and debug running pods." author: "Mohammad Abu Mattar" canonical: https://mkabumattar.com/cheatsheets/kubectl --- # kubectl kubectl is the command-line tool you use to talk to a Kubernetes cluster. Whatever you can do through a dashboard, you can do faster here: deploy apps, inspect resources, stream logs, run commands inside containers, and take nodes in and out of service. The mental model is simple. You tell kubectl a verb and a resource (`get pods`, `delete deployment`, `apply -f file.yaml`), it talks to the cluster's API server, and the cluster does the work. Get comfortable with `get`, `describe`, `logs`, and `apply` and you're already most of the way there. ## Key Features - **One tool for everything**: deploy, inspect, update, scale, and debug from a single CLI. - **Declarative or imperative**: apply YAML you keep in Git, or fire off quick one-off commands. - **Flexible output**: reshape any command into wide tables, JSON, YAML, JSONPath, or custom columns for scripting. - **Built-in debugging**: stream logs, exec into containers, attach ephemeral debug containers, and forward ports to your laptop. ## Getting Started Check your setup, switch between clusters, and find your way around the API. ### Setup and Version Confirm kubectl can reach your cluster, then make the tool faster to type. **Keywords:** version, completion, alias, kubeconfig #### Check the client and cluster versions ```bash # Show both the kubectl (client) and cluster (server) versions kubectl version # Just the client, formatted as YAML kubectl version --client -o yaml ``` If the server version is missing, kubectl can't reach the cluster yet. Check your kubeconfig before anything else. #### Turn on autocomplete and a short alias ```bash # Load completion for the current shell (add to ~/.bashrc to keep it) source <(kubectl completion bash) # use 'zsh' for zsh # Most people alias kubectl to 'k' since you type it all day alias k=kubectl ``` Autocomplete works for resource names too, not just flags, so you tab-complete pod names. It's the single biggest quality-of-life win. **Best practices:** - Add the completion line and alias to your shell profile so they survive new terminals. - Keep kubectl within one minor version of your cluster. A newer or older client can behave oddly against the API. **Common errors:** - **The connection to the server localhost:8080 was refused**: kubectl has no kubeconfig and is falling back to a local default. Set KUBECONFIG or copy a valid config to ~/.kube/config. ### Contexts and Namespaces A context bundles a cluster, a user, and a namespace. Switching contexts is how you move between clusters. **Keywords:** context, namespace, config, use-context #### See where you're pointed and switch clusters ```bash # Which contexts exist, and which one is active? kubectl config get-contexts kubectl config current-context # Switch to another cluster/context kubectl config use-context staging ``` Every command runs against the current context. When something looks wrong, check this first. You might be on the wrong cluster. #### Set a default namespace so you stop typing -n ```bash # Pin the current context to a namespace kubectl config set-context --current --namespace=payments # Override per-command when you need to kubectl get pods -n kube-system kubectl get pods -A # -A means all namespaces ``` **Best practices:** - Set a default namespace per context so you don't accidentally run commands against the wrong one. - Treat production as its own context and double-check current-context before any write command. **Common errors:** - **Resources seem to be missing even though you know they exist**: You're probably in the wrong namespace. Add -n or -A to list across all of them. ### Discovering the API When you forget a field name or a resource's short name, ask the cluster instead of guessing. **Keywords:** explain, api-resources, short names #### Look up resource types and their fields ```bash # List every resource type, its short name, and API group kubectl api-resources # Read the schema for a field, drilling down with dots kubectl explain pod.spec.containers ``` api-resources is how you learn that 'deployments' is 'deploy' for short and 'services' is 'svc'. explain saves a trip to the docs. ## Creating and Applying Resources Two styles ship work to the cluster, declarative (apply a file) and imperative (run a command). Lean on declarative. ### Apply Manifests Declarative management. You describe the desired state in YAML and let Kubernetes reconcile. **Keywords:** apply, manifest, diff, dry-run #### Apply a file, a folder, or a URL ```bash # A single manifest kubectl apply -f deployment.yaml # Every manifest in a directory (great for a whole app) kubectl apply -f ./k8s/ # Straight from a URL kubectl apply -f https://example.com/app.yaml ``` apply creates resources that don't exist and updates the ones that do, so the same command works for the first deploy and every change after. #### Preview changes before you apply them ```bash # Show exactly what would change against the live cluster kubectl diff -f deployment.yaml # Validate without touching anything (server-side) kubectl apply -f deployment.yaml --dry-run=server ``` diff is your safety net. Run it in CI and in code review so nobody is surprised by what apply actually does. **Best practices:** - Keep manifests in Git and apply them through a pipeline. The cluster should mirror your repo, not the other way around. - Run kubectl diff before applying to production so changes are never a surprise. **Common errors:** - **The "metadata.annotations: Too long" error after switching from create to apply**: A resource first made with 'create' lacks apply's tracking annotation. Re-create it with apply, or use --server-side apply going forward. ### Imperative Create Quick, one-off commands for prototyping or generating starter YAML. **Keywords:** create, run, generate yaml #### Spin up common resources from the command line ```bash # A deployment from an image kubectl create deployment web --image=nginx:1.27 # A one-shot job and a scheduled cronjob kubectl create job backup --image=postgres -- pg_dump mydb kubectl create cronjob nightly --image=busybox \ --schedule="0 2 * * *" -- /bin/sh -c 'echo run' ``` #### Let kubectl write the YAML for you ```bash # Generate a manifest without creating anything, then edit and commit it kubectl create deployment web --image=nginx \ --dry-run=client -o yaml > deployment.yaml ``` This is the fastest way to get a correct starting manifest. Generate it, tweak it, and from then on manage it with apply. **Advanced notes:** - **Imperative is fine for learning, declarative for real work:** Imperative commands are great in a terminal or an exam, but they leave no record of intent. For anything that outlives the afternoon, generate YAML and commit it. ## Viewing and Finding Resources get for the quick list, describe for the full story, and output formats for scripting. ### Get and Describe The two commands you'll run more than any other. **Keywords:** get, describe, wide, watch #### List resources, then dig into one ```bash # A quick list, then the same list with node and IP columns kubectl get pods kubectl get pods -o wide # The full picture: events, conditions, and recent state changes kubectl describe pod web-7d9f ``` describe is where you find out WHY a pod is stuck. Scroll to the Events section at the bottom first. #### Watch resources change in real time ```bash # Refresh the list as things change (Ctrl-C to stop) kubectl get pods -w # Combine resource types in one call kubectl get deploy,svc,pods ``` **Common errors:** - **A pod is stuck in Pending and you don't know why**: Run kubectl describe pod and read the Events. It usually says it can't schedule (no node fits) or can't pull the image. ### Output Formats Reshape output for humans or for scripts with -o. **Keywords:** json, yaml, jsonpath, custom-columns #### Pull out exactly the fields you need ```bash # The whole object as YAML (handy for copying spec fields) kubectl get pod web -o yaml # Just the names, one per line, via JSONPath kubectl get pods -o jsonpath='{.items[*].metadata.name}' # Your own table with custom columns kubectl get pods \ -o custom-columns='NAME:.metadata.name,NODE:.spec.nodeName' ``` JSONPath and custom-columns let you script against kubectl without piping through jq. Great for CI checks and quick reports. **Advanced notes:** - **Find the JSONPath you need:** Run the command with -o yaml first to see the structure, then walk the same path with -o jsonpath. The field names match one to one. ### Filtering and Sorting Narrow a long list down to the resources you actually care about. **Keywords:** selector, label, field-selector, sort-by #### Filter by label, field, and sort the results ```bash # Only pods with a matching label kubectl get pods -l app=web,tier=frontend # Only pods that are actually running kubectl get pods --field-selector=status.phase=Running # Sort by how many times each pod has restarted kubectl get pods \ --sort-by='.status.containerStatuses[0].restartCount' ``` Label selectors are the same ones your Services and Deployments use, so filtering with -l mirrors how Kubernetes wires things together. **Best practices:** - Label everything consistently (app, tier, env). Good labels make every selector, service, and dashboard easier. ## Updating Resources Roll out new versions, scale up and down, and tweak live objects. ### Rollouts Ship a new image and control or undo the rollout if it goes wrong. **Keywords:** rollout, set image, undo, history #### Update an image and watch the rollout ```bash # Change the container image, which triggers a rolling update kubectl set image deployment/web web=nginx:1.27.1 # Follow the rollout until it finishes (or fails) kubectl rollout status deployment/web ``` A Deployment rolls out gradually, replacing old pods with new ones, so users keep getting served while the update happens. #### Roll back a bad release ```bash # See past revisions kubectl rollout history deployment/web # Go back to the previous version kubectl rollout undo deployment/web # Or jump to a specific revision kubectl rollout undo deployment/web --to-revision=3 ``` undo is your fast path out of a broken deploy. It's much quicker than editing the image back by hand under pressure. **Common errors:** - **rollout status hangs and never completes**: New pods are probably crash-looping or failing health checks. Check kubectl get pods and kubectl logs, then roll back with rollout undo. ### Scaling Add or remove replicas, by hand or automatically. **Keywords:** scale, autoscale, replicas, hpa #### Scale manually or set up autoscaling ```bash # Run four copies of the app kubectl scale deployment/web --replicas=4 # Or let Kubernetes scale on CPU between 2 and 10 replicas kubectl autoscale deployment/web --min=2 --max=10 --cpu-percent=70 ``` autoscale creates a HorizontalPodAutoscaler. It needs the metrics-server running in the cluster to read CPU usage. ### Labels and Patches Make small, targeted changes to a live resource without re-applying the whole file. **Keywords:** label, annotate, patch, edit #### Add labels and patch a single field ```bash # Tag a pod with a label (use --overwrite to change an existing one) kubectl label pod web-7d9f environment=prod # Change one field with a strategic merge patch kubectl patch deployment/web \ -p '{"spec":{"replicas":5}}' ``` Use patch for scripted, surgical edits. Use 'kubectl edit' when you'd rather open the live object in your editor and change it by hand. **Advanced notes:** - **Live edits drift from your manifests:** Anything you change with edit, patch, or label only lives in the cluster. If you manage the resource with apply, fold the change back into your YAML or the next apply will revert it. ## Interacting With Pods Read logs, run commands inside containers, reach a pod from your laptop, and debug. ### Logs The first place to look when an app misbehaves. **Keywords:** logs, follow, previous, container #### Read and stream logs ```bash # Stream logs live (-f), only the last 100 lines to start kubectl logs -f web-7d9f --tail=100 # Pick a container in a multi-container pod kubectl logs web-7d9f -c sidecar # Logs from the previous container after a crash/restart kubectl logs web-7d9f --previous ``` --previous is the one people forget. After a crash loop, it shows the logs from the container that just died, which is exactly what you need. **Common errors:** - **a container name must be specified for pod ...**: The pod has more than one container. Add -c , or use --all-containers to stream all of them. ### Exec and Debug Get a shell or a one-off command inside a container, or attach a debug container. **Keywords:** exec, debug, run, ephemeral #### Run a command or open a shell inside a pod ```bash # One-off command kubectl exec web-7d9f -- env # Interactive shell (-it = interactive + TTY) kubectl exec -it web-7d9f -- /bin/sh ``` Everything after -- runs inside the container. Use /bin/sh if /bin/bash isn't there, since slim images often ship without bash. #### Debug a pod that has no shell at all ```bash # Attach a temporary debug container with full tools kubectl debug -it web-7d9f \ --image=busybox --target=web # Or launch a throwaway pod to poke the network kubectl run tmp --rm -it --image=busybox -- sh ``` kubectl debug adds an ephemeral container that shares the target's namespaces, so you can inspect a distroless image that has no shell of its own. **Best practices:** - Prefer kubectl debug over baking debugging tools into production images. The image stays small and the tools show up only when you need them. ### Port-Forward and Copy Reach a pod directly from your machine and move files in or out. **Keywords:** port-forward, cp, tunnel #### Tunnel a local port and copy files ```bash # Open localhost:8080 straight to the pod's port 80 kubectl port-forward pod/web-7d9f 8080:80 # Forward to whatever pod a Service points at kubectl port-forward svc/web 8080:80 # Copy a file out of a pod (tar must exist in the container) kubectl cp default/web-7d9f:/var/log/app.log ./app.log ``` port-forward is perfect for poking an internal service or a database without exposing it to the world. ### Resource Usage See which pods and nodes are actually using CPU and memory. **Keywords:** top, metrics, cpu, memory #### Check live CPU and memory ```bash # Usage per node and per pod kubectl top nodes kubectl top pods --all-namespaces ``` top needs the metrics-server add-on. If it errors out, that component probably isn't installed in the cluster. ## Cluster and Node Management Inspect the cluster as a whole and safely take nodes out of service for maintenance. ### Cluster Info A quick health read on the control plane and nodes. **Keywords:** cluster-info, get nodes, events #### Look at the cluster and recent events ```bash # Control plane endpoints kubectl cluster-info # Node list with readiness and versions kubectl get nodes -o wide # Recent events across the cluster, newest last kubectl get events --sort-by=.metadata.creationTimestamp ``` A cluster-wide events list is gold during an incident. It often points straight at the failing component. ### Node Maintenance Drain a node before you patch or reboot it, then bring it back. **Keywords:** cordon, drain, taint, uncordon #### Safely take a node down and bring it back ```bash # Stop scheduling new pods here kubectl cordon node-1 # Evict the existing pods (skip DaemonSet-managed ones) kubectl drain node-1 --ignore-daemonsets --delete-emptydir-data # ...do your maintenance, then allow scheduling again kubectl uncordon node-1 ``` drain moves pods off the node gracefully so workloads keep running elsewhere. Always cordon or drain before a reboot. **Common errors:** - **drain refuses to proceed and complains about DaemonSets or local data**: Add --ignore-daemonsets (DaemonSet pods are recreated anyway) and --delete-emptydir-data if you accept losing scratch data on that node. **Advanced notes:** - **Taints vs cordon:** cordon just stops new scheduling. A taint is more expressive, it repels pods unless they carry a matching toleration, which is how you reserve nodes for specific workloads like GPUs. ## Handy One-Liners A few commands worth keeping in your back pocket. ### Useful Patterns Small recipes that come up again and again. **Keywords:** secret, decode, force delete, jsonpath #### Decode a Secret without leaving the terminal ```bash # Secrets are base64-encoded; decode one value kubectl get secret db-creds \ -o jsonpath='{.data.password}' | base64 -d ``` Secret values are only base64-encoded, not encrypted at rest by default, so anyone with get access can read them. Lock down RBAC accordingly. #### Force-delete a pod stuck in Terminating ```bash # Last resort when a pod won't go away kubectl delete pod web-7d9f --grace-period=0 --force ``` Use this sparingly. It tells the API to forget the pod immediately even if the node never confirmed it stopped, which can leave orphaned processes if the node is actually alive. **Best practices:** - Save your favorite one-liners as shell functions or aliases. The ones you reach for during an incident should be muscle memory. **Common errors:** - **A namespace is stuck in Terminating forever**: A finalizer is usually blocking it. Find the offending resource and clear its finalizer, rather than force-deleting the namespace, which can orphan resources. ## Contexts & kubeconfig Switch between clusters, users, and namespaces, and manage merged kubeconfig files. ### Inspecting & Switching Contexts List contexts, see which is active, and change the default context or namespace. **Keywords:** config, context, namespace #### List and switch contexts ```bash kubectl config get-contexts # list contexts (* marks current) kubectl config current-context # print the active context name kubectl config use-context my-cluster # make my-cluster the default ``` get-contexts shows every cluster/user/namespace triple; use-context sets the active one. #### Pin a default namespace onto the current context ```bash kubectl config set-context --current --namespace=team-a ``` Sets a default namespace so you can drop -n on every command against this context. **Best practices:** - Set a default namespace per context with set-context --current --namespace=... instead of typing -n every time; it kills a whole class of wrong-namespace mistakes. **Common errors:** - **error: current-context must exist in order to minify.**: No context is selected. Run kubectl config use-context first, or check kubectl config get-contexts. ### Viewing & Merging kubeconfig Inspect the merged config and combine several kubeconfig files for one invocation. **Keywords:** kubeconfig, view, KUBECONFIG #### View the config for the current context only ```bash kubectl config view --minify # only the current context (redacted) kubectl config view --raw # merged config incl. cert/key data ``` --minify narrows output to the active context; --raw exposes full credentials, so handle it carefully. #### Merge multiple kubeconfig files ```bash KUBECONFIG=~/.kube/config:~/.kube/config-prod kubectl config view ``` Colon-separated list merges files for one command (use ; on Windows). **Best practices:** - Keep per-cluster kubeconfig files separate and merge them via KUBECONFIG rather than pasting everything into one file you might clobber. ## Namespaces & Labels Create namespaces and organize or filter resources with labels, annotations, and selectors. ### Namespaces Create namespaces imperatively or generate their manifests. **Keywords:** namespace, create, dry-run #### Create a namespace or generate its manifest ```bash kubectl create namespace team-a kubectl create namespace team-a --dry-run=client -o yaml > ns.yaml ``` --dry-run=client -o yaml renders the manifest without touching the cluster - handy for GitOps. **Best practices:** - Generate manifests with --dry-run=client -o yaml and commit them, rather than creating resources imperatively and losing the definition. ### Labels, Annotations & Selectors Attach metadata and filter resources with equality, set-based, and field selectors. **Keywords:** label, selector, field-selector #### Label and annotate resources ```bash kubectl label pods my-pod version=v1 kubectl label pods my-pod version=v2 --overwrite # required to change kubectl annotate pods my-pod description='owned by team-a' ``` Labels are selectable identifying metadata; annotations are non-selectable free-form metadata. #### Filter with label and field selectors ```bash kubectl get pods -l 'environment in (prod,qa)' # set-based selector kubectl get pods --show-labels # add a LABELS column kubectl get pods --field-selector=status.phase=Running # filter on fields ``` -l selects on your labels; --field-selector filters built-in fields like status.phase server-side. **Best practices:** - Use --field-selector for built-in fields (cheap, server-side) and -l for your own metadata; do not grep full output when a selector filters at the API. **Common errors:** - **label ... already has a value (v1), and --overwrite is false.**: Re-labeling needs permission to change an existing value. Add --overwrite. ## Rollouts & Scaling Drive, inspect, roll back, and scale Deployments and other rollout-capable workloads. ### Managing Rollouts Monitor progress, review history, and roll back or restart Deployments. **Keywords:** rollout, undo, restart #### Watch, roll back, and restart ```bash kubectl rollout status deployment/my-app # block until complete/failed kubectl rollout history deployment/my-app # list revisions kubectl rollout undo deployment/my-app --to-revision=2 # roll back kubectl rollout restart deployment/my-app # re-create pods (e.g. rotate secret) ``` rollout restart re-creates pods without changing the spec; undo reverts to a prior revision. - rollout pause and rollout resume let you batch several edits into a single rollout. **Best practices:** - Use kubectl rollout status in CI/CD as a gate - it exits non-zero on a failed or timed-out rollout, so the pipeline catches a bad deploy automatically. ### Scaling & Autoscaling Set fixed replica counts or attach a HorizontalPodAutoscaler. **Keywords:** scale, autoscale, hpa #### Scale manually or add an HPA ```bash kubectl scale deployment/my-app --replicas=5 kubectl scale deployment/my-app --replicas=3 --current-replicas=2 # guarded kubectl autoscale deployment/my-app --min=2 --max=10 --cpu-percent=80 ``` --current-replicas makes the scale conditional; autoscale creates an HPA targeting 80% CPU. **Best practices:** - HPAs need metrics-server and per-container resources.requests.cpu; without both, the HPA shows TARGETS /80% and never scales. **Common errors:** - **HPA shows TARGETS /80%.**: Install metrics-server (verify with kubectl top pods) and set resources.requests.cpu on the Deployment's containers. ## Debugging & Troubleshooting Inspect failing pods and nodes with ephemeral containers, events, describe, logs, and live metrics. ### Ephemeral & Node Debug Containers Attach debug containers to running pods or nodes, even for distroless images with no shell. **Keywords:** debug, ephemeral, node #### Debug a pod or a node ```bash # share the target's process namespace (great for distroless) kubectl debug -it my-pod --image=busybox:1.28 --target=my-container # a node debug pod with the host mounted at /host kubectl debug node/my-node -it --image=ubuntu ``` kubectl debug (stable since 1.25) injects an ephemeral container or a privileged node pod without editing the workload. **Best practices:** - Use --copy-to to debug a copy of a pod when you must not disturb the live one. ### Events, Logs & Metrics Read events, previous-container logs, and live resource usage to diagnose failures. **Keywords:** events, logs, top #### Events, crash logs, and usage ```bash kubectl events --for pod/my-pod # dedicated events cmd (GA 1.28) kubectl get events --sort-by=.metadata.creationTimestamp # portable form kubectl logs my-pod --previous # logs from the crashed instance kubectl top pods --containers # live CPU/memory (needs metrics-server) ``` For a CrashLoopBackOff, logs --previous shows why the dead container exited; the live one is already gone. **Best practices:** - Reach for kubectl logs --previous first on CrashLoopBackOff - the current container is already restarted, so only the previous instance's logs explain the crash. **Common errors:** - **error: Metrics API not available on kubectl top.**: metrics-server is missing or not ready. Install and verify it (kubectl get deployment metrics-server -n kube-system); top and HPAs both depend on it. ## RBAC & Access Check permissions, inspect your identity, and create RBAC objects and service accounts. ### Checking Permissions & Identity Verify what you can do and who the API server thinks you are. **Keywords:** auth, can-i, whoami #### can-i and whoami ```bash kubectl auth can-i create deployments # prints yes/no kubectl auth can-i delete pods --namespace=team-a # scope to a namespace kubectl auth can-i --list # every allowed action kubectl auth whoami # your user + groups (GA 1.28) ``` can-i answers permission questions without side effects; auth whoami is GA since Kubernetes 1.28. **Best practices:** - Before granting a Role, dry-run access with kubectl auth can-i ... --as= - cheaper and safer than binding, testing, then revoking. **Common errors:** - **kubectl auth whoami returns "the server could not find the requested resource".**: The SelfSubjectReview API is only on clusters 1.27+ (GA 1.28). Upgrade the cluster, or use kubectl config view --minify to see the configured user. ### RBAC Objects & Impersonation Create service accounts, roles, and bindings, and test access by impersonating a subject. **Keywords:** role, rolebinding, impersonation #### Create RBAC objects and impersonate ```bash kubectl create serviceaccount ci-deployer kubectl create role pod-reader --verb=get,list,watch --resource=pods kubectl create rolebinding read-pods --role=pod-reader \ --serviceaccount=default:ci-deployer kubectl get pods --as=system:serviceaccount:default:ci-deployer # verify ``` --as impersonates a user or service account (needs impersonate privilege) to check effective access. **Best practices:** - Use --clusterrole with clusterrolebinding for cluster-wide access; keep Roles namespaced and least-privilege by default. ## Output, JSONPath & Kustomize Shape output precisely, preview changes safely, and apply Kustomize overlays. ### JSONPath, Columns & Explain Extract exact fields, build custom tables, and read field documentation. **Keywords:** jsonpath, custom-columns, explain #### Shape output and read schema ```bash kubectl get pods -o jsonpath='{.items[*].metadata.name}' kubectl get nodes -o custom-columns='NAME:.metadata.name,STATUS:.status.conditions[?(@.type=="Ready")].status' kubectl explain deployment.spec.strategy --recursive ``` jsonpath and custom-columns pull exact fields; explain documents any resource path. - go-template works too, e.g. decode a secret with -o go-template='{{index .data "tls.crt" | base64decode}}'. **Best practices:** - Prefer server-side jsonpath/custom-columns over piping full output through awk/grep - it is exact and version-stable. ### Diff, Dry-run & Kustomize Preview what apply would change and build Kustomize overlays with the built-in kustomize. **Keywords:** diff, dry-run, kustomize #### Preview changes and apply an overlay ```bash kubectl diff -f app.yaml # what apply would change kubectl apply -f app.yaml --dry-run=server # validate against the API kubectl apply -k ./overlays/prod # build + apply a kustomization kubectl kustomize ./overlays/prod # render without applying ``` --dry-run takes client or server (the bare boolean form was removed); -k uses the built-in Kustomize, no separate binary. **Best practices:** - Run kubectl diff -f before every production apply - it turns a blind apply into a reviewed change and surfaces unexpected drift. **Common errors:** - **unknown flag: --dry-run printing true/false behavior.**: The bare boolean --dry-run was removed. Use --dry-run=client (local) or --dry-run=server (API-validated).