Kubernetes
container
command line
docker run
container orchestration

How do I run a container from the command line in Kubernetes like docker run?

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design

Introduction

Kubernetes does not have a perfect equivalent to docker run because it manages Pods and higher-level resources, not standalone local containers. The closest command-line match is kubectl run, which creates a Pod from an image and can optionally attach an interactive session.

The Closest Equivalent Is kubectl run

For a quick one-container Pod, kubectl run is the normal starting point.

bash
kubectl run nginx --image=nginx --restart=Never

That creates a Pod named nginx using the nginx image. The --restart=Never flag matters because it tells Kubernetes you want a plain Pod rather than a managed restart policy for a higher-level workload.

If you want an interactive shell similar to docker run -it, use a minimal image and attach standard input.

bash
1kubectl run toolbox \
2  --image=busybox \
3  --restart=Never \
4  -it \
5  -- sh

This is useful for quick troubleshooting, DNS checks, or testing outbound connectivity from inside the cluster.

Understand the Model Difference

With Docker, docker run starts one container on one machine. With Kubernetes, even a one-container Pod is still a cluster resource. The scheduler places it on a node, the API server stores its desired state, and the kubelet starts it.

That difference changes how you think about lifecycle.

  • Use a Pod for quick ad hoc work.
  • Use a Deployment for long-running stateless services.
  • Use a Job or CronJob for finite tasks.

If you only need to generate YAML instead of creating the resource immediately, dry-run is useful.

bash
1kubectl run nginx \
2  --image=nginx \
3  --restart=Never \
4  --dry-run=client -o yaml

That is often the best bridge between one-off experimentation and checked-in manifests.

Passing Commands and Arguments

You can override the image entrypoint or pass extra arguments much like Docker does.

bash
1kubectl run hello \
2  --image=busybox \
3  --restart=Never \
4  --command -- echo "hello from kubernetes"

The --command -- sequence tells kubectl that what follows should be treated as the container command rather than arguments to kubectl itself.

For temporary debugging on an existing workload, kubectl exec or kubectl debug may be better than creating a separate Pod.

When kubectl run Is Not Enough

A container that needs ports, environment variables, storage, probes, or multiple replicas quickly outgrows one-line commands. At that point, write a Pod or Deployment manifest.

yaml
1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: web
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: web
10  template:
11    metadata:
12      labels:
13        app: web
14    spec:
15      containers:
16        - name: web
17          image: nginx
18          ports:
19            - containerPort: 80

The command line is convenient for ad hoc tasks, but manifests are the reliable way to describe repeatable workloads.

That is the real dividing line. kubectl run is excellent for experimentation and debugging, but once the command becomes hard to remember, it is usually time to promote it into checked-in YAML.

Common Pitfalls

  • Expecting kubectl run to behave exactly like docker run, even though Kubernetes is creating cluster resources.
  • Forgetting --restart=Never for one-off Pods and then being surprised by different controller behavior.
  • Using kubectl run for production workloads that really deserve a Deployment or Job manifest.
  • Confusing kubectl run with kubectl exec, which attaches to an existing Pod instead of creating a new one.
  • Overriding commands incorrectly because --command -- was omitted.

Summary

  • 'kubectl run is the closest Kubernetes equivalent to docker run for quick command-line launches.'
  • It creates a Pod, not a standalone container in the Docker sense.
  • Use -it and --restart=Never for temporary interactive sessions.
  • Use dry-run output when you want to turn an ad hoc command into YAML.
  • Move to Deployments, Jobs, or manifests when the workload becomes persistent or repeatable.

Course
Beginner
27 lessons
10 hours
System Design Fundamentals

Build a strong foundation in designing scalable, reliable distributed systems.

View the course
System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design