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
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 3600Common 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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes