Imperative kubectl: Directly Command Your Cluster

Why it exists

Sometimes you need to interact with a Kubernetes cluster directly and immediately, without the overhead of writing and applying a full configuration file. Imperative commands provide a quick, command-line interface for these ad-hoc tasks, exploration, and emergencies.

The mental model

Think of imperative commands as giving direct, one-off orders to your cluster. You use verbs like run, scale, expose, and delete to tell Kubernetes what to do right now. This contrasts with the declarative approach, where you provide a YAML file describing the desired state and let Kubernetes figure out how to get there.

How it works

Commands like kubectl run my-pod --image=nginx or kubectl scale deployment/my-app --replicas=5 directly interact with the Kubernetes API server. The API server then instructs the cluster controllers to perform the requested action, such as creating a new Pod object or updating the replica count on a Deployment object. These changes happen immediately but are not persisted in a source-controlled configuration file.

When to use it

Imperative commands are ideal for exploration, debugging, and emergencies. Use them for tasks like: first, creating a temporary pod to test a network connection; second, quickly exposing a service for testing; third, manually scaling up a deployment to handle a sudden traffic spike. It's the go-to for "I need to do this right now" scenarios.

When not to use it

Do not use imperative commands for managing production infrastructure as your primary method. Because the commands are not stored in a version-controlled file, it leads to "configuration drift," where the live state of your cluster no longer matches what's in your Git repository. This makes environments difficult to reproduce, audit, or recover after a failure. For production, always prefer declarative kubectl apply -f <file.yaml>.

One canonical example

A developer needs to quickly test if a new container image works. Instead of writing a full Deployment YAML, they run kubectl run test-pod --image=my-registry/my-app:v2. This creates a single pod. After verifying it works by checking logs (kubectl logs test-pod), they can delete it with kubectl delete pod test-pod. The entire workflow is interactive and temporary.