kubectl essentials

The command line you use to read, change and inspect everything in the cluster.

kubeconfig and contexts

What: kubeconfig (~/.kube/config or $KUBECONFIG) lists clusters, users and contexts. A context pairs a cluster, a user and a default namespace.
Why: Switching context is how one laptop talks to dev, staging and production clusters.

Shell

kubectl config get-contexts
kubectl config use-context staging
kubectl config set-context --current --namespace=shop

Watch out

Running a destructive command against production because the last context used was production; show the context in your prompt.

get and describe

What: kubectl get lists objects in a table, or full YAML with -o yaml. kubectl describe shows one object in detail with its recent events.
Why: They answer "what exists and what state is it in" before you change anything.

Shell

kubectl get pods -o wide
kubectl get deploy,svc,ingress -n shop
kubectl get pod api-7c9f -o yaml
kubectl describe pod api-7c9f

apply, diff and dry runs

What: kubectl apply -f creates or updates objects to match files. kubectl diff shows what would change, and --dry-run=server validates against the live API without saving.
Why: Declarative files in Git, previewed with diff and applied with apply, make changes reviewable and repeatable.

Shell

kubectl diff -f k8s/
kubectl apply -f k8s/ --dry-run=server
kubectl apply -f k8s/
kubectl delete -f k8s/old-worker.yaml

Watch out

Mixing kubectl create or edit with apply on the same objects, which leaves fields apply no longer tracks.

Labels and selectors

What: Labels are key and value pairs on objects, like app: api. Selectors pick objects by label; Services, Deployments and NetworkPolicies all find their Pods this way.
Why: Labels are the glue of Kubernetes, and filtering by them makes kubectl output manageable.

Shell

kubectl get pods -l app=api,tier=backend
kubectl get pods --show-labels
kubectl label pod api-7c9f debug=true

Watch out

A Service selector that does not match the Pod labels exactly, so the Service has no endpoints and every request fails.

Output formats and jsonpath

What: -o yaml and -o json print full objects, -o wide adds columns, and -o jsonpath or custom-columns extract exactly the fields you want.
Why: Scripts and quick checks need one value, such as an image tag or a node name, not a screen of YAML.

Shell

kubectl get deploy api \
  -o jsonpath='{.spec.template.spec.containers[0].image}'
kubectl get pods -o custom-columns=\
NAME:.metadata.name,NODE:.spec.nodeName

kubectl explain

What: Prints the schema and documentation for any field of any resource, straight from the cluster's API.
Why: Faster than searching the docs when you forget where a field lives, and always matches your cluster version.

Shell

kubectl explain deployment.spec.strategy
kubectl explain pod.spec.containers.resources
kubectl api-resources

Manifest anatomy

What: Every object has apiVersion, kind, metadata (name, namespace, labels, annotations) and usually spec (what you want). The cluster adds status (what exists).
Why: Once you see this shape, every resource, including custom ones, reads the same way.

Watch out

Committing status, resourceVersion or uid from kubectl get -o yaml into Git; strip server-set fields.

Go deeper