Overview
kubectl talks to the cluster named by your current context and namespace. Check both before any change. Container-level commands are in docker-commands; commands follow the official kubectl quick reference.
Context and namespace
Confirm context and namespace before any apply or delete.
| Command | Effect |
|---|---|
kubectl config get-contexts / current-context | List contexts / show the active one. |
kubectl config use-context <name> | Switch cluster. |
kubectl config set-context --current --namespace=staging | Default namespace for this context. |
Inspect
Run describe before logs when a pod will not start.
| Command | Effect |
|---|---|
kubectl get pods -A | Pods in all namespaces. |
kubectl get nodes, kubectl describe node <node> | Node status, capacity, and conditions. |
kubectl get pods -n staging -l app=api -o wide | Filter by namespace and label; adds node and IP columns. |
kubectl describe pod <pod> | Conditions and Events; start here for Pending or CrashLoopBackOff. |
kubectl get events --sort-by=.lastTimestamp | Recent events, newest last (or kubectl events). |
kubectl top pods | CPU and memory; needs metrics-server. |
kubectl get pod <pod> -o yaml | Full live manifest. |
Apply and roll back
Prefer apply and diff over imperative edits.
| Command | Effect |
|---|---|
kubectl apply -f deploy.yaml | Create or update; also -f ./dir/ or -k ./overlay/. |
kubectl diff -f deploy.yaml | Preview the change. |
kubectl delete -f deploy.yaml | Delete what the file declares. |
kubectl rollout status deploy/api | Wait for a rollout. |
kubectl rollout history deploy/api | Revisions. |
kubectl rollout undo deploy/api [--to-revision=3] | Roll back one step or to a revision. |
kubectl rollout restart deploy/api | Recreate pods with the same spec. |
kubectl scale deploy api --replicas=3 | Change replicas. |
kubectl set image deploy/api api=myapp:v2 | Update an image. |
Logs, exec, debug
Use --previous for crashed containers and debug for images without a shell.
| Command | Effect |
|---|---|
kubectl logs -f <pod> [-c <container>] | Stream logs. |
kubectl logs --previous <pod> | Logs of the crashed container. |
kubectl logs -l app=api --tail=50 | Logs across a label (default tail is 10 with a selector). |
kubectl exec -it <pod> -- sh | Shell in a pod; exec <pod> -- env runs one command. |
kubectl cp <pod>:/app/err.log ./err.log | Copy a file out; needs tar in the image. |
kubectl debug -it <pod> --image=busybox --target=<container> | Ephemeral debug container for shell-less images. |
Port-forward
Use port-forward for local access instead of exposing a service.
| Command | Effect |
|---|---|
kubectl port-forward pod/<pod> 8080:8080 | Local 8080 to the pod. |
kubectl port-forward svc/api 8080:80 | Through a Service (still pins to one pod); deploy/api works too. |
kubectl port-forward svc/db 5432:5432 | Reach a cluster database from a local client. |
Shortnames and selectors
Use shortnames and label selectors to cut typing and scope commands.
| Resource | Short | Resource | Short |
|---|---|---|---|
pods | po | statefulsets | sts |
services | svc | daemonsets | ds |
deployments | deploy | cronjobs | cj |
replicasets | rs | persistentvolumeclaims | pvc |
configmaps | cm | ingresses | ing |
namespaces | ns | nodes | no |
kubectl api-resources lists every resource with its shortname and whether it is namespaced. Label selectors: -l key=value, -l key!=value, -l 'key in (a,b)'. Field selector: --field-selector status.phase=Running.
Gotchas
Avoid these; each acts on the wrong namespace or fights a controller.
| Gotcha | Fix |
|---|---|
Commands act on the context’s namespace (default unless set). | Pass -n, or set the namespace on the context. |
kubectl delete pod on a managed pod just gets a replacement. | Scale to 0 or delete the Deployment. |
kubectl get all omits ConfigMaps, Secrets, and Ingresses. | Name the resource types you need. |
rollout undo goes back one revision. | Use --to-revision, and keep manifests in git. |
port-forward dies when its pod restarts. | Re-run it, or expose the service properly. |
kubectl exec fails on distroless images. | Use kubectl debug. |