kubectl Mastery

1. Philosophy

kubectl is your primary interface to Kubernetes. Master it like you master awk.

This page covers kubectl command patterns. For deployment runbooks, see:

  • infra-ops: k3s Deployment, k3s Operations

  • infra-ops: Kubernetes Architecture Reference

2. Essential Patterns

2.1. Get with Output Control

# Wide output (more columns)
kubectl get pods -o wide

# YAML output (full object)
kubectl get pod <name> -o yaml

# JSON for jq processing
kubectl get pods -o json | jq '.items[].metadata.name'

# Custom columns (like awk for k8s)
kubectl get pods -o custom-columns=\
'NAME:.metadata.name,STATUS:.status.phase,IP:.status.podIP,NODE:.spec.nodeName'

# JSONPath (surgical extraction)
kubectl get pods -o jsonpath='{.items[*].metadata.name}'

2.2. Namespace Operations

# All namespaces
kubectl get pods -A
kubectl get pods --all-namespaces

# Specific namespace
kubectl get pods -n monitoring

# Set default namespace for session
kubectl config set-context --current --namespace=monitoring

2.3. Label Selectors

# Equality
kubectl get pods -l app=nginx

# Set-based
kubectl get pods -l 'app in (nginx,traefik)'

# Multiple conditions (AND)
kubectl get pods -l app=nginx,tier=frontend

# Show labels
kubectl get pods --show-labels

3. Debugging Patterns

3.1. Pod Diagnostics

# Describe (events, conditions, mounts)
kubectl describe pod <name>

# Logs (current)
kubectl logs <pod>

# Logs (previous crash)
kubectl logs <pod> --previous

# Logs (specific container in multi-container pod)
kubectl logs <pod> -c <container>

# Follow logs (like tail -f)
kubectl logs -f <pod>

# Logs since time
kubectl logs --since=1h <pod>
kubectl logs --since-time=2024-01-15T10:00:00Z <pod>

3.2. Interactive Debugging

# Exec into running container
kubectl exec -it <pod> -- /bin/sh
kubectl exec -it <pod> -- /bin/bash

# Exec specific container
kubectl exec -it <pod> -c <container> -- /bin/sh

# Run command without shell
kubectl exec <pod> -- cat /etc/resolv.conf

# Port forward for local access
kubectl port-forward pod/<pod> 8080:80
kubectl port-forward svc/<service> 8080:80

3.3. Events (Cluster-Wide Debugging)

# Recent events (sorted)
kubectl get events --sort-by='.lastTimestamp'

# Events for specific resource
kubectl get events --field-selector involvedObject.name=<pod>

# Watch events live
kubectl get events -w

4. Advanced Queries with jq

4.1. Pod Analysis

# Pods not Running
kubectl get pods -A -o json | jq -r '
  .items[] | select(.status.phase != "Running") |
  [.metadata.namespace, .metadata.name, .status.phase] | @tsv'

# Container restart counts
kubectl get pods -A -o json | jq -r '
  .items[] | .metadata as $m |
  .status.containerStatuses[]? |
  select(.restartCount > 0) |
  [$m.namespace, $m.name, .name, .restartCount] | @tsv' | column -t

# Pods by node
kubectl get pods -A -o json | jq -r '
  .items[] | [.spec.nodeName, .metadata.namespace, .metadata.name] | @tsv' |
  sort | column -t

4.2. Resource Utilization

# CPU/Memory requests vs limits
kubectl get pods -A -o json | jq -r '
  .items[] | .metadata as $m |
  .spec.containers[] |
  [$m.namespace, $m.name, .name,
   (.resources.requests.cpu // "none"),
   (.resources.limits.cpu // "none"),
   (.resources.requests.memory // "none"),
   (.resources.limits.memory // "none")] | @tsv' | column -t

# Nodes capacity
kubectl get nodes -o json | jq -r '
  .items[] | [.metadata.name,
   .status.capacity.cpu,
   .status.capacity.memory,
   .status.allocatable.cpu,
   .status.allocatable.memory] | @tsv' | column -t

4.3. Service Discovery

# Services with endpoints
kubectl get svc -A -o json | jq -r '
  .items[] | [.metadata.namespace, .metadata.name,
   .spec.type, .spec.clusterIP,
   (.spec.ports | map("\(.port)/\(.protocol)") | join(","))] | @tsv' | column -t

# Ingress hosts and paths
kubectl get ingress -A -o json | jq -r '
  .items[] | .metadata as $m |
  .spec.rules[]? | .host as $h |
  .http.paths[] |
  [$m.namespace, $m.name, $h, .path, .backend.service.name] | @tsv' | column -t

5. Custom Columns Recipes

# Pod status summary
kubectl get pods -A -o custom-columns=\
'NAMESPACE:.metadata.namespace,NAME:.metadata.name,READY:.status.containerStatuses[*].ready,STATUS:.status.phase,RESTARTS:.status.containerStatuses[*].restartCount,AGE:.metadata.creationTimestamp,NODE:.spec.nodeName'

# Deployments with replicas
kubectl get deploy -A -o custom-columns=\
'NAMESPACE:.metadata.namespace,NAME:.metadata.name,DESIRED:.spec.replicas,READY:.status.readyReplicas,AVAILABLE:.status.availableReplicas,AGE:.metadata.creationTimestamp'

# PVCs with storage class
kubectl get pvc -A -o custom-columns=\
'NAMESPACE:.metadata.namespace,NAME:.metadata.name,STATUS:.status.phase,CAPACITY:.status.capacity.storage,STORAGECLASS:.spec.storageClassName,VOLUME:.spec.volumeName'

6. Context and Config

# View current context
kubectl config current-context

# List all contexts
kubectl config get-contexts

# Switch context
kubectl config use-context <context-name>

# View merged kubeconfig
kubectl config view

# Set default namespace
kubectl config set-context --current --namespace=<ns>

7. Declarative Operations

# Apply manifest
kubectl apply -f manifest.yaml

# Apply directory
kubectl apply -f ./manifests/

# Apply from URL
kubectl apply -f https://raw.githubusercontent.com/...

# Dry run (client-side)
kubectl apply -f manifest.yaml --dry-run=client

# Dry run (server-side validation)
kubectl apply -f manifest.yaml --dry-run=server

# Diff before apply
kubectl diff -f manifest.yaml

8. Quick Reference

Task Command

Get all resources in namespace

kubectl get all -n <ns>

Delete pod (force restart)

kubectl delete pod <name>

Scale deployment

kubectl scale deploy/<name> --replicas=3

Rollout status

kubectl rollout status deploy/<name>

Rollback deployment

kubectl rollout undo deploy/<name>

Top pods (metrics-server required)

kubectl top pods

Top nodes

kubectl top nodes

API resources list

kubectl api-resources

Explain resource fields

kubectl explain pod.spec.containers

9. Aliases (Add to .bashrc/.zshrc)

alias k='kubectl'
alias kgp='kubectl get pods'
alias kgpa='kubectl get pods -A'
alias kgs='kubectl get svc'
alias kgn='kubectl get nodes'
alias kd='kubectl describe'
alias kl='kubectl logs'
alias klf='kubectl logs -f'
alias ke='kubectl exec -it'
alias kaf='kubectl apply -f'
alias kdf='kubectl delete -f'

# With namespace
alias kn='kubectl -n'

10. Shell Completion

# Bash
echo 'source <(kubectl completion bash)' >> ~/.bashrc

# Zsh
echo 'source <(kubectl completion zsh)' >> ~/.zshrc

# With alias
echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc

11. Related

  • jq & yq Mastery - JSON processing for kubectl output

  • infra-ops: Kubernetes Architecture Reference

  • infra-ops: k3s Operations & Maintenance