Services

Resources

Company

/

kubectl

kubectl

kubectl is the command-line client for Kubernetes. Every command it runs becomes a request to the cluster's API server, the same API that controllers, CI jobs and dashboards use. kubectl get pods -n shop is an HTTPS GET /api/v1/namespaces/shop/pods; add -v=6 and kubectl prints the URL of each request it makes.

How it works

kubectl finds the cluster through a kubeconfig file, ~/.kube/config unless KUBECONFIG points elsewhere. The file lists clusters (API server URL and CA certificate), users (a client certificate, a token, or an exec plugin such as aws eks get-token) and contexts, which pair a cluster with a user and a default namespace. kubectl config get-contexts lists them and kubectl config use-context staging switches. The context is the setting that hurts people: the same kubectl delete means something very different on prod.

Most days need a dozen verbs:

  • get and describe read state

  • logs and exec look inside a container

  • apply -f sends a manifest

  • rollout status and rollout undo follow or reverse a Deployment

  • port-forward reaches a pod from your laptop

  • top shows CPU and memory if metrics-server is installed

Before changing anything, kubectl diff -f shows what an apply would change on the live object, and kubectl apply --dry-run=server runs the request through validation and admission without saving it.

For example, checkout errors climb after a release:

  1. kubectl config current-context confirms prod.

  2. kubectl get pods -n shop -l app=checkout shows 2 of 3 pods Running and one in CrashLoopBackOff with 5 restarts. The kubelet doubles the wait between restarts, starting at 10 s, so after 5 restarts that pod has sat idle for over 5 minutes.

  3. kubectl describe pod shows the last state as OOMKilled with exit code 137 (128 plus signal 9) against a memory limit of 256Mi. kubectl logs --previous shows what the dead container printed before it was killed.

  4. The limit goes to 512Mi in the manifest. kubectl diff shows that as the only change, kubectl apply sends it, and kubectl rollout status deployment/checkout -n shop waits until 3 of 3 are ready.

Why it matters in production

kubectl is the fastest way to find out what a cluster is doing, and a risky way to change it. A change made by hand leaves no review and no record in Git, and the next pipeline run or GitOps sync may quietly undo it. Many teams keep write access in prod for break-glass use and do routine changes through CI.

Keep kubectl within one minor version of the API server, which is the skew Kubernetes supports. When a Horizontal Pod Autoscaler or a Deployment misbehaves, kubectl describe and its Events section are where to look first.

See also

On the One2N blog

References

  1. Kubernetes docs: Command line tool (kubectl)

  2. Kubernetes docs: Organizing cluster access using kubeconfig files

Routing diagram of kubectl: the command kubectl get pods -n shop goes through the kubeconfig file, ~/.kube/config, which lists two contexts, staging and prod. A red arrow marks prod as the current context, warning that the same delete hits prod. A green arrow carries the request, GET /api/v1/namespaces/shop/pods, to the prod API server, while a grey dashed arrow to staging is the path not taken.