kubectl-run

Run an nginx pod and expose port 80

$ kubectl run [nginx-dev] --image nginx --port 80

$ kubectl run [nginx-dev] --image nginx --env "[TEST_VAR]=[testing]"

$ kubectl run [nginx-dev] --image nginx --dry-run=[none|server|client]

$ kubectl run [temp-ubuntu] --image ubuntu:22.04 --restart Never --rm -- /bin/bash

$ kubectl run [temp-ubuntu] --image ubuntu:22.04 --command -- echo [argument1 argument2 ...]

kubectl run NAME --image=image [--env="key=value"] [--port=PORT] [--dry-run=server|client|none] [--rm] [--restart=POLICY] [-n NAMESPACE] [options]

--allow-missing-template-keys
    If true, a template without a corresponding Go template is created

--attach
    Attach to a running container (default false)

--cascade
    If true, cascade the deletion of resources tracked by garbage collector (default true)

--command
    Command passed to generated container; if empty, uses image's default or shell

--dry-run
    Dry run mode: client|server|none (default none)

--env
    Environment variables as key=value pairs

--expose
    Create a service exposing the pod (default false)

--force
    Force replacement if resource exists

--generator
    Controller generator to use (e.g., deployment/v1beta1; deprecated)

--hostport
    Host port to expose container port on

--image
    Container image to run

--image-pull-policy
    Image pull policy (IfNotPresent|Always|Never)

--overrides
    Strategic merge patch JSON/YAML overriding defaults

--pod-running-timeout
    Timeout for pod to be running before considered failed

--port
    Port to expose on pod

--quiet
    Suppress informational output (default false)

--replicas
    Number of replicas (default 1)

--replace
    Replace existing resource if found (default false)

--restart
    Restart policy: Always (deployment), OnFailure/Never (job), Never (pod)

--rm
    Delete resource on exit (default false)

--save-config
    Store generated config in annotation

--serviceaccount
    ServiceAccount to run as

--stdin
    Keep stdin open on the container (default false)

--template
    Go template for output

--tty
    Allocate a TTY for the container (default false)

kubectl run quickly creates and starts one or more pods in a Kubernetes cluster using a specified container image. It supports creating simple pods, interactive sessions, or higher-level resources like Deployments (default), Jobs, or ReplicaSets based on flags such as --restart or --generator.

Common use cases include testing container images, debugging with interactive shells (-it --rm), ad-hoc jobs, or prototyping services with auto-exposed ports. Options allow setting environment variables, commands, ports, replicas, and service accounts.

However, this command is deprecated since Kubernetes v1.18. It now defaults to creating a Deployment instead of a Pod, which may surprise users expecting simple pod behavior. Kubernetes recommends explicit alternatives like kubectl create deployment, kubectl create job, or declarative YAML with kubectl apply for better reproducibility and GitOps practices. Despite deprecation, it remains supported for compatibility.

Deprecated: Defaults to Deployment creation; use explicit kubectl create or kubectl apply instead.
Behavior changed in v1.18+; may break scripts.
Not suitable for production due to imperative nature.

kubectl run nginx --image=nginx
Creates Deployment with 1 nginx replica.

kubectl run debug --image=busybox --rm -it --restart=Never -- sh
Interactive shell; pod auto-deletes on exit.

kubectl run myjob --image=busybox --restart=OnFailure -- echo "hello"
Creates Job that runs once.

Replace with kubectl create deployment NAME --image=image for Deployments, or kubectl run NAME --image=image --restart=Never explicitly for pods (deprecated behavior).

Introduced in Kubernetes v1.0 (2014) for simple imperative pod creation. Evolved with generators for Deployments/ReplicaSets/Jobs. Default generator changed to Deployment in v1.18 (2020), marking deprecation. Further restricted in v1.23+; expected removal in future major versions.

kubectl(1), kubectl create(1), kubectl apply(1), kubectl exec(1), kubectl delete(1), docker run(1)