Start your free 14-day ContainIQ trial

Using Kubectl Run | Tutorial and Examples

In this guide, we highlight the kubectl run command and provide an actionable example alongside helpful context.

July 14, 2022
Kumar Harsh
Software Developer

Kubernetes is a container orchestration framework that can help you scale hundreds of app containers to meet your user traffic. Kubernetes provides powerful features and tools to manage K8s clusters. <terminal inline>kubectl<terminal inline>, an open-source CLI, is one of the popular command-line tools used by engineers to interact with a K8s cluster.

In this guide, we will take a look at <terminal inline>kubectl run<terminal inline>, a command that is used to run container images on Kubernetes resources.

What is kubectl run Used For?

As stated before, the <terminal inline>kubectl run<terminal inline> 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 --image=nginx

You will receive a similar output:

pod/nginx created

You can now view the newly created pod by running <terminal inline>kubectl get pods<terminal inline>.

Monitor Kubernetes Events in Real-Time
Monitor the health of your cluster and troubleshoot issues faster with pre-built dashboards that just work.
Learn More Book a Demo
event dashboard

Using ‘–port’ and ‘–dry-run’ with kubectl run

Some useful options offered with the run command include:


You can control the port that the newly created instance will expose. Here’s how you can use it:

kubectl run nginx --image-nginx --port=5701


This is possibly one of the most useful options offered with this command. The dry-run option allows you to test the effects of a <terminal inline>kubectl run<terminal inline> call without actually running in on your live cluster. Here’s how you can use it:

kubectl run nginx --image=nginx --dry-run

If you couple it with the <terminal inline>-o yaml<terminal inline> option, you can see the manifest that was generated for your new pod. The dry-run option is also offered for some other useful commands like create, apply, patch, etc.

kubectl run Best Practices

Here are a few best practices you should know when using <terminal inline>kubectl run<terminal inline>.

--command vs --arguments

You might want to run commands on your newly created pods. You can either append them to your kubectl run call like this:

kubectl run nginx --image=nginx -- 'echo hello;sleep 3600'

Or, you could pass them as commands, like this:

kubectl run nginx --image=nginx --command -- 'echo hello;sleep 3600'

While they might appear similar, they are handled quite differently by K8s. If you are looking to run a command, always prefer the <terminal inline>--command<terminal inline> option as it will override the <terminal inline>EntryPoint<terminal inline> and <terminal inline>Cmd<terminal inline> defined in your container and run your command directly. While in the other case, your command will be passed as an argument to the <terminal inline>EntryPoint<terminal inline> and <terminal inline>Cmd<terminal inline> calls, and the final results can vary.

Creating deployment

<terminal inline>kubectl run<terminal inline> was earlier used to create deployments as well. However, with Kubernetes 1.18, <terminal inline>kubectl run<terminal inline> 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 <terminal inline>kubectl create deployment<terminal inline> command.

Final Thoughts

You will often feel the need to create pods and image instances on the fly when working with Kubernetes. The <terminal inline>kubectl run<terminal inline> command can help you do just that. In this guide, we showed you how you can achieve the same and also shared a few tips to keep in mind when using the <terminal inline>kubectl run<terminal inline> command.

Start your free 14-day ContainIQ trial
Start Free TrialBook a Demo
No card required
Kumar Harsh
Software Developer

Kumar is a software developer and technical author. He has written for a number of software companies including LogRocket and Career Karma. Kumar previously worked for Goldman Sachs as a Summer Analyst. He is currently pursuing a Bachelor of Technology in Computer Science at the National Institute of Technology, Patna.