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] [--command -- COMMAND [ARGS...]]

--image=IMAGE
    The container image to use for the Pod. This is a mandatory argument.

NAME
    The name to assign to the new Pod being created.

--restart=POLICY
    Defines the Pod's restart policy (e.g., Always, Never, OnFailure). Default is Always.

--env=KEY=VALUE
    Set environment variables in the container. Can be specified multiple times for different variables.

--port=PORT
    Port number to expose on the Pod's container.

--labels=KEY=VALUE
    Labels to apply to the Pod, in a key=value format.

--rm
    Delete the Pod after it terminates. This flag is effective only when --restart=Never.

--attach
    Attach to the container's stdin/stdout/stderr, similar to docker attach.

--command
    If present, the arguments following -- will be treated as the container's command, prepended to its entrypoint.

--dry-run=MODE
    Print the object to stdout without sending it to the API server (e.g., client, server).

--stdin
    Keep stdin open for the container.

--tty
    Allocate a TTY for the container.

--namespace=NAMESPACE
    If present, the namespace scope for this request.

kubectl run is a command used to create and run a new Pod in Kubernetes. Primarily designed for quick tests, debugging, or ephemeral tasks, it takes a container image as its main argument.

Historically, kubectl run was more versatile, capable of creating Deployments, Jobs, or ReplicaSets using --generator flags. However, to simplify its role and avoid overlap with kubectl create and kubectl apply, its functionality was streamlined in Kubernetes versions 1.18+ to default to Pod creation only. This shift firmly establishes its purpose as a convenient tool for running temporary containers directly in the cluster without needing higher-level controllers.

Functionality Evolution: Prior to Kubernetes 1.18, kubectl run created various resource types (Deployments, Jobs, etc.) using --generator. This functionality is now deprecated, and kubectl run strictly creates Pods by default. Relying on deprecated generators is discouraged as they will be removed.

Ephemeral Pods: Pods created directly by kubectl run (without a higher-level controller like Deployment) are not automatically restarted or managed if they fail, are evicted, or the node goes down. For resilient applications, use kubectl create deployment or kubectl apply.

Security Considerations: Running arbitrary images, especially with --attach or --stdin, requires caution. Untrusted images can pose security risks to your cluster or local environment.

A common usage pattern for kubectl run is to obtain an interactive shell inside a container, similar to docker run -it. This is typically achieved using kubectl run --rm -it --command -- image-name -- /bin/bash. The --rm flag ensures the Pod is automatically deleted upon session exit.

It's an excellent tool for quickly spinning up a container to test network connectivity within the cluster, verify DNS resolution, or run a single diagnostic command, without the overhead of creating a Deployment. Its simplicity makes it ideal for one-off tasks.

kubectl run initially emerged as a highly versatile command, allowing users to rapidly create various Kubernetes resource types, such as Deployments, Jobs, and ReplicaSets, by specifying different --generator flags. This made it a popular choice for quick prototyping and setup.

However, its broad functionality led to ambiguity and overlap with more explicit commands like kubectl create and kubectl apply. To simplify the command-line interface and reduce confusion, a significant change was introduced.

Starting with Kubernetes 1.18, the --generator flag became officially deprecated, and the default behavior of kubectl run was changed to exclusively create a Pod. This change streamlined its purpose, making it a dedicated tool for running temporary, single-container instances, often for debugging or interactive sessions.

The deprecated --generator flag is expected to be removed in future Kubernetes releases, solidifying kubectl run's current role as a Pod-centric command.

kubectl create(1), kubectl apply(1), kubectl exec(1), kubectl attach(1), kubectl logs(1)