Kubernetes Kubectl Reference

Comprehensive reference for kubernetes kubectl reference covering essential concepts, practical examples, and production best practices.

Kubectl is the command-line interface for managing Kubernetes clusters. Use it to deploy applications, inspect running pods, scale services, troubleshoot failures, and update configurations—all from the terminal. This reference documents precise, production-grade usage patterns, common pitfalls, and exact syntax for kubectl operations that engineers rely on daily.

Deploying Applications

Apply a Configuration from a File

kubectl apply -f deployment.yaml

Applies the configuration in deployment.yaml to the cluster. Creates or updates resources based on the apiVersion, kind, and metadata.name.

Key behavior:

Common pitfall:

Use --prune to remove obsolete resources:

kubectl apply -f manifests/ --prune --selector=app=nginx

Rollout a Deployment

kubectl rollout status deployment/frontend
kubectl rollout history deployment/frontend
kubectl rollout undo deployment/frontend --to-revision=3

Sharp edge:

Inspecting and Troubleshooting

View Logs from a Pod

kubectl logs frontend-7d5b9c4b8f
kubectl logs -f frontend-7d5b9c4b8f
kubectl logs -c nginx frontend-7d5b9c4b8f
kubectl logs -c nginx --tail=50 frontend-7d5b9c4b8f
kubectl logs -c nginx --since=1h --timestamps frontend-7d5b9c4b8f

Critical gotcha:

  kubectl logs -f -c app --tail=0 --since=0 --timestamps frontend-7d5b9c4b8f

Debug a Pod with Interactive Shell

kubectl exec -it frontend-7d5b9c4b8f -- /bin/sh
kubectl exec -it frontend-7d5b9c4b8f -c nginx -- bash
kubectl exec -it frontend-7d5b9c4b8f -- ls -la /app

Common mistake:

  # Wrong: runs 'ls -la' on local machine
  kubectl exec -it pod-123 -- ls -la /app

  # Correct: runs 'ls -la' inside the pod
  kubectl exec -it pod-123 -- sh -c 'ls -la /app'

Describe Resources

kubectl describe pod/frontend-7d5b9c4b8f
kubectl describe deployment/frontend
kubectl describe svc/frontend
kubectl describe nodes

Useful for diagnosing:

Managing Configurations

Patch a Resource

kubectl patch deployment/frontend -p '{"spec":{"replicas":5}}'
kubectl patch deployment/frontend -p '{"metadata":{"labels":{"env":"prod"}}}' --type=merge
kubectl patch deployment/frontend -p '{"spec":{"template":{"spec":{"containers":[{"name":"app","image":"new:latest"}]}}}}' --type=merge

Critical behavior:

Use --patch-format=merge or --patch-format=strategic to force the patch type.

Create or Update ConfigMaps and Secrets

kubectl create configmap app-config --from-file=app.conf --from-literal=debug=true
kubectl create secret generic db-creds --from-file=creds.json --from-literal=password=secret123
kubectl apply -f configmap.yaml
kubectl apply -f secret.yaml

Key gotcha:

  kubectl apply -f configmap.yaml --force

Set and View Resource Annotations

kubectl annotate pod/frontend-7d5b9c4b8f "deployer=jenkins" "release=1.2.3"
kubectl annotate pod/frontend-7d5b9c4b8f "deployer=jenkins" --overwrite
kubectl annotate pod/frontend-7d5b9c4b8f "monitoring=true" --all
kubectl annotate pod/frontend-7d5b9c4b8f "monitoring=true" --local -f - --save-config

Use --local with --save-config to persist changes to a file before applying to the cluster.

Scaling and Upgrading

Scale a Deployment or ReplicaSet

kubectl scale deployment/frontend --replicas=10
kubectl scale deployment/frontend --current-replicas=5 --replicas=10
kubectl scale deployment/frontend --replicas=5 -l env=prod

Critical detail:

  kubectl scale deployment/frontend --replicas=10
  kubectl rollout status deployment/frontend

Rollout a New Image

kubectl set image deployment/frontend app=nginx:latest --record
kubectl set image deployment/frontend app=nginx:1.21 --record --all

Important:

  kubectl set image deployment/frontend app=nginx:latest --record --save-config

Advanced: Working with Contexts and Configurations

Switch Between Clusters and Contexts

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

Sharp edge:

  kubectl config use-context prod-cluster --namespace=prod

View and Modify kubeconfig

kubectl config view
kubectl config view --output=yaml
kubectl config view --output=json
kubectl config get-clusters
kubectl config get-contexts
kubectl config get-namespaces
kubectl config set-cluster prod-cluster --server=https://prod.example.com
kubectl config set-credentials jenkins --token=abc123

Tip:

Failure Modes and Debugging

Common Errors and Their Fixes

→ The pod name is incorrect or the pod is not in the current namespace. Use kubectl get pods -A to list pods across all namespaces.

→ A container in the pod is already listening on port 80. Check the container’s livenessProbe and readinessProbe.

→ The Kubernetes API server is under load or has a misconfigured etcd. Check kubectl get events -A and kubectl describe pod <pod>.

→ The flag is not recognized by the current version of kubectl. Use kubectl version to verify the version and kubectl help to see available flags.

Use kubectl get with Custom Columns

kubectl get pods -o=custom-columns=NAME:.metadata.name,STATUS:.status.phase,AGE:.metadata.creationTimestamp
  kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

Use case:

  kubectl get pods -o=custom-columns=NAME:.metadata.name,READY:.status.readyReplicas,UPDATES:.status.updateRevision --no-headers

> Note: All commands assume the current context is set via kubectl config use-context. Use kubectl config current-context to verify.

This page was rewritten on 10 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.