Declarative vs. Imperative Models in Kubernetes

Previously in this course, we explored the anatomy of a Kubernetes cluster and how the control plane acts as the brain of your operations. Today, we’re moving from understanding the architecture to mastering how we actually interact with it.

To be an effective engineer, you must shift your mindset from "doing" to "defining."

The Imperative Approach: "How" to Do It

The imperative model is familiar to anyone who has used a CLI or written a bash script. You give the system a direct command, and it executes it immediately.

If you want to run a container in an imperative style, you might run: kubectl run my-nginx --image=nginx

You are acting as the operator. You are telling the API server: "Create a resource with this name and this image." If that command succeeds, the action is done. However, if the pod crashes later, or if you accidentally delete it, the cluster doesn't necessarily know that you wanted that pod to stay alive. You have to issue more imperative commands to fix the state.

The Declarative Approach: "What" I Want

Declarative management is the heart of Kubernetes. Instead of telling the cluster what to do, you tell it what the final state should look like. You write this down in a YAML file—a manifest—that defines your desired state.

When you apply this file, Kubernetes compares your "desired state" with the "actual state" currently running in the cluster. It then calculates the difference and makes the necessary changes to reach your target.

The Reconciliation Loop: The Secret Sauce

The core of this declarative model is the Reconciliation Loop (often called the Control Loop).

1. Observe: The controller watches the current state of the cluster via the API server.
2. Diff: It compares the current state to the desired state defined in your manifest.
3. Act: If there is a mismatch, the controller performs actions (creating, updating, or deleting resources) to close the gap.

This loop runs continuously. If a pod dies, the controller notices the "actual" count is 0 while the "desired" count is 1, and it instantly schedules a new pod to restore your configuration.

Worked Example: Comparing the Two

Let's look at the difference in practice.

Imperative: You run: kubectl create deployment nginx --image=nginx The command is sent, the deployment is created. If you want to change the image, you have to run another command: kubectl set image deployment/nginx nginx=nginx:1.21. This is hard to track over time.

Declarative: You create a file named deployment.yaml:

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: nginx
        image: nginx:1.19

To update the image, you simply edit the file to say image: nginx:1.21 and run kubectl apply -f deployment.yaml. The cluster sees the change and reconciles the deployment to match your new file.

Hands-on Exercise

1. Try an imperative command: Run kubectl create deployment demo --image=nginx.
2. Inspect the resource: Run kubectl get deployments.
3. Delete it: Run kubectl delete deployment demo.
4. Reflect: Notice how you had to manually issue a delete command? In the next section of the course, we will move to creating these as YAML files, which allows us to keep our infrastructure in source control.

Common Pitfalls

• Mixing models: The biggest mistake beginners make is using kubectl edit or kubectl patch to change a live resource without updating the original YAML manifest. This creates "configuration drift," where your cluster state no longer matches your source of truth.
• Over-reliance on imperative commands: While kubectl run is great for quick debugging, it is poor practice for production infrastructure. Always aim to move your definitions into version-controlled manifests as soon as possible.
• Ignoring the loop: Sometimes the reconciliation loop takes a few seconds. Beginners often panic and run another command because the resource didn't appear instantly. Give the controller a moment to observe and act.

FAQ

Q: Is imperative ever useful? A: Yes! Imperative commands are excellent for quick troubleshooting, gathering logs, or ad-hoc debugging sessions where you don't need to persist a configuration.

Q: Can I use both? A: You can, but it’s a path to madness. Stick to declarative manifests for anything that needs to be repeatable or long-running.

Q: What is a "state store"? A: As discussed in our previous look at the control plane, the state store (etcd) holds the truth about the cluster. The reconciliation loop ensures the actual world matches what is recorded in that store.

Recap

You’ve learned that Kubernetes is fundamentally a declarative system. By using manifests and the reconciliation loop, you define the "what," and the cluster handles the "how." This shift is critical for building scalable, self-healing infrastructure.

Up next: Setting Up Your Local Environment so you can start applying these manifests yourself.