How to use kubectl run

kubectl run is a scratchpad command. It creates a pod quickly, which makes it useful for testing images, commands, ports, and small debugging scenarios.

It should not become your deployment workflow. Real workloads need manifests, version control, repeatability, and review. For ML teams, that line matters because one-off pods are easy to create and hard to reproduce.

The examples assume a configured kubectl context and permission to create Pods in a disposable namespace. Check the context, then create the namespace used below:

kubectl config current-context
kubectl create namespace kubectl-run-demo

The stable image tags keep these examples readable. Pin an approved image version or digest when saving a workload for repeatable use.

What is Kubectl Run used for?

As stated before, the kubectl run command helps you to run container images on your Kubernetes pods. The syntax for the command is simple:

You can provide a name for the running instance of the image using the name field. Here's how you can create a pod with a basic nginx server:

kubectl run nginx --namespace kubectl-run-demo --image=nginx:stable

# Output

pod/nginx created

You can now view the newly created Pod with kubectl get pods --namespace kubectl-run-demo. Creating the resource does not mean its image has been pulled or its container is ready.

Using --port and --dry-run with Kubectl Run

Some useful options offered with the run command include:

--port

You can declare a container port in the Pod specification. NGINX's default configuration listens on port 80, so the declaration below matches the application:

kubectl run nginx-port --namespace kubectl-run-demo --image=nginx:stable --port=80

# Output

pod/nginx-port created

--port does not reconfigure NGINX's listener, publish a host port, or create a Kubernetes Service. To reach this Pod from your computer, wait for readiness and open a local tunnel:

kubectl wait --namespace kubectl-run-demo --for=condition=Ready pod/nginx-port --timeout=120s
kubectl port-forward --namespace kubectl-run-demo pod/nginx-port 8080:80

Open http://localhost:8080 while the forwarding command is running.

--dry-run

The --dry-run=client option generates the object without submitting it to the API server. Pair it with -o yaml to inspect or save the manifest:

kubectl run nginx-manifest --namespace kubectl-run-demo --image=nginx:stable --dry-run=client -o yaml

Client dry-run does not check admission policies, image availability, or whether the cluster can run the Pod. --dry-run=server submits a dry-run request for server-side validation without persisting the resource; it still does not start the container. See the kubectl run reference for the supported flags.

Kubectl Run best practices

Here are a few best practices you should know when using kubectl run.

Container commands and arguments

Arguments after -- normally populate the container's args, replacing the image's default CMD while retaining its ENTRYPOINT. For an NGINX image, this supplies an explicit server command to the image's entrypoint script:

kubectl run nginx-args --namespace kubectl-run-demo --image=nginx:stable -- nginx -g 'daemon off;'

With --command, the values after -- populate the container's command instead. Use an explicit shell when you need shell syntax such as ;:

kubectl run hello --namespace kubectl-run-demo --image=busybox:stable --restart=Never --command -- sh -c 'echo hello; sleep 3600'

Kubernetes does not split a quoted string into a program and its arguments or automatically interpret shell operators. Here, the executable is sh, and -c tells that shell to interpret the following string. The Pod's logs should contain hello, after which the container sleeps. The choice between command and args depends on whether you want to keep the image's entrypoint.

Creating deployment

kubectl run was earlier used to create deployments as well. However, with Kubernetes 1.18, kubectl run was updated to only create pods and it lost its deployment-specific options as well. If you are looking to create a deployment, you should instead use the kubectl create deployment command.

See Kubernetes workloads basics for complete Pod, Job, Deployment, and Service examples. When finished with this walkthrough, stop the local port-forward and remove only its disposable namespace:

kubectl delete namespace kubectl-run-demo

Final thoughts

kubectl run is good for quick experiments and throwaway pods. It is bad as a long-term deployment habit. If the workload matters, put the configuration in a manifest or a higher-level workload spec.

Polyaxon gives ML teams that repeatable layer for jobs and services. You can still debug with kubectl, but production training and serving should not depend on terminal history.