kubectl

kubectl is the command-line client that talks to kube-apiserver on your behalf — every other page in this course has already shown you dozens of its commands in passing, because there's no way to touch a real cluster without it. This page is the tool guide those pages point back to: the three genuinely different ways kubectl lets you manage an object (and why mixing them causes real incidents), the --dry-run=client -o yaml trick that turns any one-liner into a starting manifest, how a kubeconfig's contexts and namespaces decide which cluster your next command actually hits, kubectl explain as a live, self-updating reference for any resource including your own CRDs, and how to extend the CLI itself with krew plugins. It closes with the gotchas that show up once kubectl stops being a toy on a laptop and starts being the thing three different people and a CI pipeline all point at the same production cluster with.

What kubectl actually is

☺ Like you're 10: It's not magic and it's not special — it reads a config file to find your cluster, turns what you typed into a web request, and prints back whatever the server says.

The Kubernetes API & the controller pattern already covers this in depth, so only the short version belongs here: kubectl reads your kubeconfig (usually ~/.kube/config) to find a cluster's address and your credentials, turns the verb and resource you typed into an HTTPS request against kube-apiserver, and pretty-prints whatever JSON comes back. It carries no special privilege of its own — a curl request with the same bearer token gets treated identically by the same RBAC and admission checks. That means everything below is really about one thing: how precisely you can control which request kubectl sends, and to which cluster.

Three ways to manage an object — and why mixing them bites

☺ Like you're 10: You can tell kubectl exactly what to do right now, hand it a whole file to swap in, or hand it a file and let it figure out only what changed — and those three are not interchangeable habits.

Kubernetes documentation draws this distinction formally, and it's worth taking seriously rather than treating all three as "ways to run kubectl":

• Imperative commands — kubectl run, kubectl create deployment, kubectl expose, kubectl scale, kubectl set image — act directly on the live object. No file exists anywhere; the command is the record, and once your shell history scrolls past it, the intent is gone.
• Imperative object configuration — kubectl create -f file.yaml, kubectl replace -f file.yaml, kubectl delete -f file.yaml — you write a whole file, but the command still operates on the entire object. replace is a full overwrite: whatever is live gets discarded and swapped for exactly what's in the file, full stop.
• Declarative object configuration — kubectl apply -f file.yaml — you describe desired state and let kubectl work out the difference. This is the one this course's Foundations and object model pages assume by default, and the one GitOps controllers like Argo CD and Flux use under the hood.

apply's trick is a three-way merge. It doesn't just diff your file against the live object — it also reads a third source: the kubectl.kubernetes.io/last-applied-configuration annotation, a JSON snapshot of the file you applied last time, which apply silently writes onto the object as it goes. Comparing all three lets it answer a much more precise question than replace ever can: "did this specific field actually change in what I'm managing, or did something else change it out from under me?"

# apply preserves fields it didn't tell it to change
$ kubectl apply -f deployment.yaml                    # replicas: 3, last-applied now says 3
$ kubectl scale deployment/web --replicas=7            # something else (you, an HPA) bumps live to 7
$ kubectl apply -f deployment.yaml                     # file still says 3, unchanged since last-applied
# → apply sees file == last-applied for replicas, so it leaves the LIVE value (7) alone

# kubectl diff shows you the same three-way comparison apply would act on, before it acts
$ kubectl diff -f deployment.yaml

The other trap is switching styles mid-object. An object created with kubectl create or kubectl run has no last-applied-configuration annotation, because nothing declarative ever touched it. The first kubectl apply -f against that object prints a warning and falls back to treating the live object as if last-applied were empty — safe in the common case, but the honest fix is to pick one management style per object and stay in it, which is exactly why this course's own manifests are all written and re-applied with apply, never mixed with imperative edits in between.

--dry-run=client -o yaml: your manifest generator

☺ Like you're 10: Type the quick imperative command you already know, add two flags, and kubectl hands you back a real starter YAML file instead of actually doing anything.

Every imperative kubectl create and kubectl expose subcommand builds a full object in memory before it ever sends it anywhere — --dry-run=client stops it right there and -o yaml prints the object instead of submitting it. The result is a syntactically correct, sensibly defaulted manifest for exactly the object you described, in seconds, which beats hand-typing Deployment boilerplate from memory or a half-remembered example every time.

# scaffold a Deployment, edit the result, then apply it for real
$ kubectl create deployment web --image=nginx:1.27 --replicas=3 --dry-run=client -o yaml > deployment.yaml

# same trick for a Service, a ConfigMap, and a Job
$ kubectl create service clusterip web --tcp=80:8080 --dry-run=client -o yaml > service.yaml
$ kubectl create configmap web-config --from-literal=LOG_LEVEL=info --dry-run=client -o yaml > configmap.yaml
$ kubectl expose deployment web --port=80 --target-port=8080 --dry-run=client -o yaml

$ kubectl apply -f deployment.yaml -f service.yaml -f configmap.yaml

--dry-run=client never leaves your machine — it doesn't even need a reachable cluster. --dry-run=server is the stricter sibling: kubectl submits the request to the real API server, which runs it through defaulting, validation, and every admission webhook that would normally fire, and then reports what would happen — without persisting it. That catches things client-side dry-run structurally can't, like a validating webhook rejecting the object or a mutating webhook injecting a sidecar, which is exactly why kubectl apply -f manifest.yaml --dry-run=server earns a spot as a pre-flight check in CI, ahead of the real apply.

Contexts & namespaces: which cluster, which corner of it

☺ Like you're 10: Your kubeconfig can remember several TVs at once — a context is which TV, which remote control code, and which room in that TV you're currently pointed at.

A kubeconfig file is three lists and one pointer: clusters (a name, a server URL, a CA certificate), users (a name, and credentials — a client cert, a token, or an exec plugin that fetches one on the fly), and contexts (a name that ties one cluster to one user, plus an optional default namespace). current-context is the pointer saying which of those tuples every bare kubectl command uses right now.

# ~/.kube/config — abbreviated
apiVersion: v1
kind: Config
current-context: staging
clusters:
- name: staging-cluster
  cluster: { server: https://staging.k8s.internal:6443, certificate-authority: ca.crt }
- name: prod-cluster
  cluster: { server: https://prod.k8s.internal:6443, certificate-authority: ca.crt }
users:
- name: prashant
  user: { exec: { command: aws, args: ["eks", "get-token", "--cluster-name", "prod"] } }
contexts:
- name: staging
  context: { cluster: staging-cluster, user: prashant, namespace: checkout }
- name: prod
  context: { cluster: prod-cluster, user: prashant, namespace: checkout }

$ kubectl config get-contexts                                # list every context, mark the current one
$ kubectl config current-context                              # just the pointer
$ kubectl config use-context prod                              # flip the pointer
$ kubectl config set-context --current --namespace=checkout    # change the current context's default namespace
$ kubectl config view --minify                                 # only the currently active cluster/user/context

KUBECONFIG can list several files separated by : (or ; on Windows), and kubectl merges them into one logical config — the common pattern is one file per cluster, checked out from wherever that cluster's operator hands them out, merged automatically rather than hand-edited into a single giant file.

A shared cluster credential means current-context is shared, mutable, hidden state — the exact opposite of a safe thing to rely on right before typing kubectl delete namespace checkout. Two habits fix that. First, plugins: kubectl krew install ctx ns gives you kubectl ctx and kubectl ns — fast, fuzzy-searchable switchers modeled on Ahmet Alp Balkan's original kubectx/kubens — and most shell prompt integrations (a Powerlevel10k segment, an oh-my-zsh plugin) print the current context and namespace on every line, so you see it before you type, not after you've already run the command. Second, scripts and CI should never depend on ambient current-context at all — pass --context and --namespace explicitly on every invocation, so a pipeline behaves identically no matter what some human last left the shared runner's kubeconfig pointed at.

kubectl explain: reading the API's own schema

☺ Like you're 10: Instead of Googling "what fields does a Deployment have," you just ask the cluster itself — it always has the current, correct answer.

kubectl explain reads the OpenAPI schema kube-apiserver publishes about itself (the same schema the API & controller pattern page covers as the discovery mechanism behind server-side validation), field by field, with the description text the API's own maintainers wrote. Because it queries the live server rather than a bundled, potentially-stale copy, it's automatically correct for whatever Kubernetes version the cluster is actually running — and it works identically on a CRD your platform team shipped yesterday, as long as that CRD's openAPIV3Schema is filled in.

$ kubectl explain deployment                                       # top-level fields, one paragraph each
$ kubectl explain deployment.spec.strategy                          # drill into one nested field
$ kubectl explain deployment.spec.template.spec.containers.resources --recursive   # the whole subtree at once
$ kubectl explain --api-version=batch/v1 cronjob.spec.schedule      # pin the version if more than one is served
$ kubectl explain database.spec                                     # works on your own CRD identically

Reach for it before reaching for a search engine any time a manifest field's exact meaning, type, or valid values are in doubt — it's faster, it's always in sync with the cluster in front of you, and unlike most blog posts it can't be answering for a Kubernetes version two years out of date.

Extending the CLI: plugins via krew

☺ Like you're 10: kubectl can learn new tricks — anyone can write one and hand it to you, and krew is just the app store that finds and installs them.

A kubectl plugin is nothing more exotic than an executable named kubectl-something sitting somewhere on your PATH — kubectl scans for that naming convention on startup, and kubectl something runs it, passing along any extra arguments. There's no registration step and no compiled-in list; the convention alone is the whole mechanism. krew is a plugin manager built on top of that convention: it maintains a searchable index of community plugins, handles the download and install for your OS/architecture, and — being itself installed as a kubectl plugin — even upgrades itself the same way.

# one-time krew install: see krew.sigs.k8s.io for the current official snippet per OS
$ export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"

$ kubectl krew search                          # browse the whole index
$ kubectl krew install ctx ns neat tree who-can # install several plugins at once
$ kubectl krew list                             # what's installed
$ kubectl krew upgrade                          # upgrade everything, including krew itself

A handful earn a permanent spot on most clusters people actually operate: ctx/ns for fast context and namespace switching (covered above); neat, which strips managedFields, resourceVersion, and other server-generated noise out of a kubectl get -o yaml so the output is something you'd actually want to read or re-apply; tree, which walks the ownerReferences chain from the object model page to print an object and everything it owns as one indented tree — a Deployment, its ReplicaSets, and their Pods, in one glance; and who-can, which answers "which subjects can do this verb on this resource" directly from live RBAC bindings, instead of you tracing RoleBindings by hand.

Day-to-day commands

☺ Like you're 10: A short list covers most of what you'll type in any given hour — look, describe, read logs, get inside, and roll back if it goes wrong.

# the read loop: what exists, why, and what it's saying
$ kubectl get pods -n checkout -o wide
$ kubectl describe pod checkout-7d9f4c-x8k2q -n checkout
$ kubectl logs -f checkout-7d9f4c-x8k2q -n checkout --previous       # --previous: the crashed container's last log

# getting inside a running (or not-quite-running) container
$ kubectl exec -it checkout-7d9f4c-x8k2q -n checkout -- sh
$ kubectl port-forward svc/checkout 8080:80 -n checkout
$ kubectl cp checkout-7d9f4c-x8k2q:/var/log/app.log ./app.log -n checkout

# surgical edits without a full apply
$ kubectl patch deployment checkout -n checkout -p '{"spec":{"replicas":5}}'
$ kubectl label pod checkout-7d9f4c-x8k2q tier=backend -n checkout
$ kubectl annotate deployment checkout kubernetes.io/change-cause="bump to 1.5.0" -n checkout

# rollouts, and backing out of one
$ kubectl rollout status deployment/checkout -n checkout
$ kubectl rollout undo deployment/checkout -n checkout --to-revision=3

# resource pressure and blocking waits, useful in scripts
$ kubectl top pods -n checkout --sort-by=memory
$ kubectl wait --for=condition=Available deployment/checkout -n checkout --timeout=120s

Gotchas and failure modes

☺ Like you're 10: Most kubectl mistakes aren't typos — they're the CLI doing exactly what you told it, in a cluster or namespace you didn't mean.

The unnamespaced default is default, silently. Any command without -n and without a context-level default namespace set lands in the default namespace — not "wherever you were last," not an error. A script that assumes it inherited a namespace from a previous cd-style command is assuming something kubectl never promised.

--field-selector is not a general filter. Unlike -l/label selectors, which match any label you've set, --field-selector only works against a small, resource-specific allow-list (status.phase, metadata.name, spec.nodeName, and a handful more) — trying it against an arbitrary field returns a "field label not supported" error, not the filtered list you expected.

kubectl exec needs a shell that exists and a container that's actually running. Against a CrashLoopBackOff Pod, or a distroless image with no shell at all, exec simply fails. kubectl debug solves both: kubectl debug -it checkout-7d9f4c-x8k2q --image=busybox --target=checkout -n checkout attaches an ephemeral container that shares the target container's process namespace, giving you a shell and a set of tools next to a container that never had either.

kubectl get all doesn't get all. It's a fixed, hardcoded list of common resource types — it silently excludes ConfigMaps, Secrets, ResourceQuotas, and any CRD-backed resource, regardless of what actually exists in the namespace. Treat it as a quick glance, never as a complete inventory.

A long-running -w/--watch can die quietly. The underlying watch connection can be closed by the API server (an idle timeout, an apiserver restart during a rolling upgrade) without kubectl automatically reconnecting in older versions — a terminal that looks like it's still live-tailing may in fact have gone stale minutes ago. For anything you actually need to trust, prefer a tool built to reconnect — k9s's live views handle this for you — over a bare -w left running unattended.

kubectl vs. the alternatives

☺ Like you're 10: Other tools give you a nicer window onto the exact same cluster — none of them replace kubectl, they mostly sit on top of it.

Note what's deliberately absent from that table: Helm and Kustomize aren't kubectl alternatives at all — they're templating and packaging layers that ultimately still hand kubectl (or the same API kubectl talks to) a fully-rendered manifest. Asking "kubectl or Helm" is the same category error as asking "Ansible or Terraform" on the DevOps course's Ansible page — different jobs, routinely used together, not competitors for the same slot.