kubectl is the command-line client for every Kubernetes cluster — kubeadm, k3s or managed. This reference covers the commands that matter for day-to-day operations, grouped by task.

Setup and context

kubectl version
kubectl cluster-info
kubectl config get-contexts             # clusters/users you can use
kubectl config use-context prod
kubectl config set-context --current --namespace=shop   # default namespace

Shell completion and an alias save a lot of typing:

echo 'source <(kubectl completion bash)' >> ~/.bashrc
echo 'alias k=kubectl; complete -o default -F __start_kubectl k' >> ~/.bashrc

Viewing resources

kubectl get nodes -o wide
kubectl get pods                        # current namespace
kubectl get pods -A                     # all namespaces
kubectl get pods -o wide                # node and IP
kubectl get deploy,svc,ingress
kubectl get pods -l app=web             # by label
kubectl get pods --field-selector status.phase!=Running
kubectl get events --sort-by=.lastTimestamp | tail -20
kubectl get all -n shop

Details and recent events for one object:

kubectl describe pod web-7d9f8c-abcde
kubectl describe node worker-1

describe is where you find why a pod is Pending (insufficient resources, unbound volume) or crashing (image pull errors, failed probes).

Output formats

kubectl get pod web-7d9f8c-abcde -o yaml
kubectl get pods -o jsonpath='{.items[*].metadata.name}'
kubectl get pods -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,STATUS:.status.phase
kubectl get deploy web -o yaml > web.yaml        # export for editing

Logs

kubectl logs web-7d9f8c-abcde
kubectl logs -f deploy/web                       # follow, picks a pod
kubectl logs web-7d9f8c-abcde -c sidecar         # specific container
kubectl logs web-7d9f8c-abcde --previous         # the crashed instance before restart
kubectl logs -l app=web --tail=50 --prefix       # several pods by label
kubectl logs deploy/web --since=1h

--previous is essential for CrashLoopBackOff: it shows the output of the container that just died.

Exec and debugging

kubectl exec -it web-7d9f8c-abcde -- sh
kubectl exec deploy/web -- env
kubectl debug -it web-7d9f8c-abcde --image=nicolaka/netshoot --target=web   # ephemeral debug container
kubectl run tmp --rm -it --image=busybox --restart=Never -- sh             # throwaway pod
kubectl top nodes                                # needs metrics-server
kubectl top pods -A --sort-by=memory

Applying and changing resources

kubectl apply -f app.yaml
kubectl apply -f k8s/                            # a whole directory
kubectl apply -k overlays/prod                   # kustomize
kubectl diff -f app.yaml                         # what would change
kubectl delete -f app.yaml
kubectl edit deploy web                          # edit live (prefer files in Git)
kubectl set image deploy/web web=registry.example.com/web:1.4.2
kubectl label pod web-7d9f8c-abcde tier=frontend
kubectl annotate deploy web team=payments

Deployments and rollouts

kubectl rollout status deploy/web
kubectl rollout history deploy/web
kubectl rollout undo deploy/web                  # back to previous revision
kubectl rollout undo deploy/web --to-revision=3
kubectl rollout restart deploy/web               # restart pods (e.g. after a ConfigMap change)
kubectl scale deploy/web --replicas=5
kubectl autoscale deploy/web --min=2 --max=10 --cpu-percent=70

Networking

kubectl port-forward svc/web 8080:80             # localhost:8080 → service
kubectl port-forward pod/postgres-0 5432:5432
kubectl get endpoints web                        # which pods back the service
kubectl get ingress -A

port-forward is the safe way to reach internal services (databases, dashboards) without exposing them.

Config and secrets

kubectl create configmap app-config --from-file=config.yaml
kubectl create secret generic db --from-literal=password='s3cret'
kubectl get secret db -o jsonpath='{.data.password}' | base64 -d

Secrets are only base64-encoded, not encrypted, unless your cluster encrypts them at rest. See ConfigMaps and Secrets.

Nodes and maintenance

kubectl cordon worker-1                          # no new pods
kubectl drain worker-1 --ignore-daemonsets --delete-emptydir-data
kubectl uncordon worker-1
kubectl taint nodes worker-1 dedicated=db:NoSchedule

Common pod states and what to check

Status Look at
Pending describe pod → events: resources, node selectors, PVC binding
ImagePullBackOff Image name/tag, registry credentials (imagePullSecrets)
CrashLoopBackOff logs --previous, command/args, env vars, probes
OOMKilled Memory limits too low, or a leak
Running but not ready Readiness probe, describe events

More in debugging Kubernetes pods.

Handy tools

  • k9s — a terminal UI for browsing and managing clusters.
  • kubectx / kubens — fast context and namespace switching.
  • stern — tail logs from many pods at once.

Need a cluster to practise on? k3s sets one up on a single VPS in minutes.

  • Kubernetes
  • kubectl
  • DevOps