kubectl run: Usage, Options & Common CI Errors

Spin up a throwaway pod for a quick test or debug shell.

kubectl run starts a single pod from an image. In modern Kubernetes it creates a bare pod (not a Deployment), which makes it ideal for one-off debug containers and CI smoke checks.

What it does

kubectl run NAME --image=IMG creates one pod. --rm -it --restart=Never gives a throwaway interactive container that is deleted on exit - perfect for poking the cluster network. --restart=Never makes it a plain pod (vs the default that historically made other controllers). --command -- overrides the entrypoint.

Common usage

Terminal

kubectl run tmp --rm -it --image=busybox --restart=Never -- sh
kubectl run curl --rm -it --image=curlimages/curl --restart=Never \
  -- curl -s http://web.default.svc/health
kubectl run dbg --image=nicolaka/netshoot --restart=Never -- sleep 3600

Common errors in CI

With --rm -it in a pipeline that has no TTY, drop -t (keep -i if you pipe input) or the step hangs. "ImagePullBackOff" on a debug pod is a typo'd image or a private registry without an imagePullSecret. A classic gotcha: without --restart=Never, an interactive --rm pod that the controller may restart can leak; always pair throwaway runs with --restart=Never. For debugging an existing pod's namespace, prefer kubectl debug over run.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl debug: Usage, Options & Common CI Errorskubectl debug attaches an ephemeral debug container to a running pod. Debugging distroless pods, node debuggi… kubectl exec: Usage, Options & Common CI Errorskubectl exec runs a command inside a running container. Interactive shells, the -- separator, and the connect… kubectl create: Usage, Options & Common CI Errorskubectl create imperatively creates resources and scaffolds manifests. create vs apply, --dry-run YAML, and t…