kubectl run

When to Use kubectl run

kubectl run creates a single pod and is the fastest way to run a container in Kubernetes. It is primarily used for testing, debugging, and quick experiments. For production workloads, always use Deployments or other controllers that provide self-healing and scaling.

Quick Debugging Patterns

The most common use of kubectl run is spinning up temporary pods for debugging cluster issues:

# Interactive shell for general debugging
kubectl run debug --image=busybox -it --rm --restart=Never -- /bin/sh

# Test DNS resolution
kubectl run dns-test --image=busybox -it --rm --restart=Never -- nslookup my-service

# Test HTTP connectivity to a service
kubectl run curl-test --image=curlimages/curl -it --rm --restart=Never -- \
  curl -s http://my-service.default.svc.cluster.local

# Test database connectivity
kubectl run pg-test --image=postgres:16 -it --rm --restart=Never -- \
  psql -h db-host -U admin -d mydb -c "SELECT 1"

# Test with a specific service account
kubectl run debug --image=busybox -it --rm --restart=Never \
  --overrides='{"spec":{"serviceAccountName":"my-sa"}}' -- /bin/sh

The -it --rm --restart=Never combination is the standard pattern for ephemeral debug pods: interactive, temporary, and non-restarting.

Generating Pod Manifests

Use kubectl run with --dry-run=client -o yaml to generate starter manifests:

# Generate a basic pod manifest
kubectl run web --image=nginx:1.25 --port=80 \
  --dry-run=client -o yaml > pod.yaml

# Generate with labels
kubectl run web --image=nginx:1.25 \
  --labels="app=web,tier=frontend" \
  --dry-run=client -o yaml > pod.yaml

This is faster than writing YAML from scratch and ensures the output is valid.

Using Overrides

The --overrides flag lets you customize the pod spec beyond what the standard flags support:

# Run on a specific node
kubectl run debug --image=busybox -it --rm --restart=Never \
  --overrides='{"spec":{"nodeName":"worker-2"}}'

# Run with a specific security context
kubectl run debug --image=busybox -it --rm --restart=Never \
  --overrides='{"spec":{"securityContext":{"runAsUser":1000}}}'

# Mount a volume from a PVC
kubectl run debug --image=busybox -it --rm --restart=Never \
  --overrides='{
    "spec": {
      "containers": [{
        "name": "debug",
        "image": "busybox",
        "stdin": true,
        "tty": true,
        "volumeMounts": [{"name": "data", "mountPath": "/data"}]
      }],
      "volumes": [{"name": "data", "persistentVolumeClaim": {"claimName": "my-pvc"}}]
    }
  }'

Testing Network Policies

kubectl run is valuable for testing network policies by running pods in different namespaces and verifying connectivity:

# Create a test pod in the source namespace
kubectl run test-source --image=curlimages/curl -n frontend \
  -it --rm --restart=Never -- curl -s -m 5 http://api.backend.svc.cluster.local

# Test if traffic is blocked
kubectl run test-blocked --image=curlimages/curl -n untrusted \
  -it --rm --restart=Never -- curl -s -m 5 http://api.backend.svc.cluster.local

CKA/CKAD Exam Tips

In Kubernetes certification exams, kubectl run is essential for quickly creating pods without writing YAML:

# Create a pod quickly
kubectl run nginx --image=nginx:1.25

# Create a pod and expose it
kubectl run web --image=nginx --port=80
kubectl expose pod web --port=80 --target-port=80

# Create a pod with specific commands
kubectl run busybox --image=busybox --restart=Never -- sleep 3600

The --dry-run=client -o yaml pattern is also heavily used to generate manifests that you then edit to add volumes, probes, or init containers.

Cleanup

Temporary pods created without --rm will persist after they complete. Clean them up regularly:

# Find completed pods
kubectl get pods --field-selector=status.phase=Succeeded

# Delete completed pods
kubectl delete pods --field-selector=status.phase=Succeeded

# Delete failed pods
kubectl delete pods --field-selector=status.phase=Failed

Best Practices

Always use --rm with -it for debug sessions so pods are automatically cleaned up. Never use kubectl run for production workloads. Use --restart=Never for one-shot commands. Use --dry-run=client -o yaml to generate manifests instead of remembering complex YAML structures.