kubectl commands

The exact kubectl command and flag for each task, grouped the way you work at a terminal, for kubectl v1.37. What the objects are and why they behave as they do is in Kubernetes; chart releases are driven with Helm commands.

Setup

v=$(curl -Ls https://dl.k8s.io/release/stable.txt)
u="https://dl.k8s.io/release/$v/bin/linux/amd64"
curl -LO "$u/kubectl" && curl -LO "$u/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum -c
sudo install -m 0755 kubectl /usr/local/bin/kubectl

Swap amd64 for arm64 on ARM, or $v for a fixed version such as v1.37.2.

Version skew: kubectl is supported within one minor version of the API server, older or newer, so a v1.37 client covers 1.36 to 1.38 control planes.

Kubeconfig and contexts

A kubeconfig file lists clusters (API URL and CA), users (credentials) and contexts (a cluster, a user and a default namespace), plus the current-context.

kubectx and kubens

Install with brew install kubectx or kubectl krew install ctx ns (then kubectl ctx, kubectl ns). With fzf installed, running either without arguments opens a picker.

Command anatomy

kubectl  get   deploy/api   -n web -o yaml
         verb  TYPE/NAME    flags

Short names

Secrets, Jobs, Roles and RoleBindings have no short name.

Discovering kinds and fields

Reading resources

Output formats

JSONPath has no regular expressions: pipe -o json into jq for those. On Windows, wrap the template in double quotes and use single quotes inside it.

# name and node of every Pod, tab-separated
t='{range .items[*]}{.metadata.name}{"\t"}'
t+='{.spec.nodeName}{"\n"}{end}'
kubectl get pods -o jsonpath="$t"
 
# Pods with their image(s), as a table
kubectl get pods -o custom-columns=\
'POD:.metadata.name,IMAGE:.spec.containers[*].image'

Selectors

Pod field selectors also accept spec.restartPolicy, spec.serviceAccountName, status.podIP; Events accept involvedObject.name, involvedObject.kind, reason, type.

Creating and changing

apply and diff

Generators: create and run

Every create and run accepts --dry-run=client -o yaml, which prints the object instead of creating it: the fastest way to start a manifest.

kubectl create deploy api --image=ghcr.io/acme/api:1.4.2 \
  --replicas=3 --port=3000 --dry-run=client -o yaml \
  > deploy.yaml
kubectl create service clusterip api --tcp=80:3000 \
  --dry-run=client -o yaml > svc.yaml
kubectl run tmp --image=busybox:1.37 --restart=Never \
  --dry-run=client -o yaml -- sleep 3600 > pod.yaml

ConfigMap, Secret and token generators are in ConfigMaps and Secrets.

edit, patch and replace

Labels, annotations and set

Deleting

Workloads and rollouts

status, history, undo and restart work on Deployments, DaemonSets and StatefulSets. restart sets a kubectl.kubernetes.io/restartedAt annotation on the Pod template, which is also why it is the usual way to pick up changed ConfigMap or Secret values.

Logs, exec and port-forward

port-forward to a Service or Deployment picks one Pod and stays on it, with no load balancing; it ends when that Pod goes away.

Debugging

kubectl debug

Ephemeral containers can't be removed: they stay in the Pod until it is deleted. Node debug Pods (node-debugger-worker-2-…) and --copy-to copies stay until you delete them.

Events and usage

Events are kept for about an hour by default. top needs metrics-server and shows a short recent average, not a peak.

See the status-by-status flowchart in Kubernetes debugging for what to look at once you have the output.

Nodes

drain uses the Eviction API, which honors PodDisruptionBudgets: if a PDB allows no disruption right now, drain keeps retrying until --timeout.

Access and RBAC

The who-can plugin answers the reverse question: kubectl who-can delete pods -n web.

ConfigMaps and Secrets

create fails if the object exists. To create or update in one step, generate and apply:

kubectl create configmap api-config --from-file=app.toml \
  --dry-run=client -o yaml | kubectl apply -f -
# env vars never reload: restart the Pods
kubectl rollout restart deploy/api

Waiting

kubectl wait blocks until a condition holds; it waits 30 s by default (--timeout; 0 checks once).

Plugins and krew

A plugin is any executable named kubectl-name on your PATH; kubectl name runs it (kubectl-foo-bar becomes kubectl foo bar). kubectl plugin list shows what it finds. krew is the plugin manager: install it with brew install krew or the script on the krew site, then add ${KREW_ROOT:-$HOME/.krew}/bin to your PATH.

Outside kubectl, k9s is a terminal UI for the same tasks (k9s -n web).

Shell setup

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

# after compinit; the k alias completes automatically
echo 'source <(kubectl completion zsh)' >> ~/.zshrc
echo 'alias k=kubectl' >> ~/.zshrc

kubectl completion fish \
  > ~/.config/fish/completions/kubectl.fish
abbr --add k kubectl

kubectl completion powershell |
  Out-String | Invoke-Expression
Set-Alias -Name k -Value kubectl

alias k=kubectl
alias kg='kubectl get'
alias kd='kubectl describe'
alias kaf='kubectl apply -f'
alias kl='kubectl logs -f'
alias kx='kubectl exec -it'
alias kns='kubectl config set-context --current --namespace'
# scaffold YAML: k create deploy api --image=x $dry
export dry='--dry-run=client -o yaml'

kuberc (~/.kube/kuberc, or the file in KUBERC; KUBERC=off disables it) holds kubectl preferences separate from cluster credentials: default flags per command and your own aliases. Flags you type still win.

apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
defaults:
  - command: delete
    options:
      - name: interactive      # always confirm deletes
        default: "true"
  - command: apply
    options:
      - name: server-side
        default: "true"
aliases:                  # getn = get nodes -o wide
  - name: getn
    command: get
    prependArgs: [nodes]
    options:
      - name: output
        default: wide

kubectl kuberc view prints it; kubectl kuberc set --section aliases --name getn --command get --prependarg nodes --option output=wide writes the same alias for you.

Quick lookup

References

• kubectl reference (opens in a new tab): every command and flag, generated from the source
• kubectl overview (opens in a new tab): syntax, resource types, output options
• kubectl Quick Reference (opens in a new tab): the official cheat sheet
• JSONPath support (opens in a new tab): operators, filters, escaping, Windows quoting
• Install tools (opens in a new tab): kubectl install per platform
• Version skew policy (opens in a new tab): which kubectl works with which cluster
• Organizing cluster access with kubeconfig (opens in a new tab): merge rules and precedence
• Configure access to multiple clusters (opens in a new tab): contexts step by step
• kuberc (opens in a new tab): preferences file format
• Labels and selectors (opens in a new tab) and field selectors (opens in a new tab)
• Update API objects with kubectl patch (opens in a new tab): strategic, merge and JSON patches
• Server-side apply (opens in a new tab): field managers and conflicts
• Debug running Pods (opens in a new tab) and debugging nodes with kubectl (opens in a new tab)
• Safely drain a node (opens in a new tab): drains and PodDisruptionBudgets
• Force delete StatefulSet Pods (opens in a new tab): why --force is dangerous
• Extend kubectl with plugins (opens in a new tab) and krew (opens in a new tab), with its plugin index (opens in a new tab)
• kubectx and kubens (opens in a new tab), stern (opens in a new tab), k9s (opens in a new tab): the usual companions