Kubernetes' Declarative Model: Desired vs. Actual State

WHY IT EXISTS: To manage complex, distributed systems reliably. Giving a system step-by-step instructions (the imperative model) is brittle and doesn't handle failures well. Describing a target state (the declarative model) allows the system to be self-healing and resilient to unexpected changes.

THE MENTAL MODEL: Think of it as setting a thermostat. You don't tell the furnace to turn on and off; you set the desired temperature to 70°F. The thermostat (the Kubernetes controller) constantly compares the actual temperature (the cluster's actual state) to your setting (the desired state from your file) and takes action to close the gap. You define 'what,' not 'how.'

HOW IT WORKS: You write a manifest file, usually in YAML, that describes Kubernetes objects like Deployments, Services, or ConfigMaps. You use the command kubectl apply -f your-file.yaml. The Kubernetes API server receives this desired state. Controller loops then run in the background, observing the cluster's current state and making changes to match the desired state you provided. For example, a ReplicaSet controller ensures the correct number of pods are always running.

WHEN TO USE IT: This is the standard, recommended practice for managing all production Kubernetes resources. It's essential for infrastructure-as-code, GitOps workflows, and creating repeatable, version-controlled environments. Use kubectl apply as your default for managing application lifecycles.

WHEN NOT TO USE IT: Imperative commands are acceptable for quick, one-off, interactive tasks. For example, using kubectl run to launch a temporary debugging pod or kubectl exec to get a shell inside a container. These are for exploration, not for managing long-lived application state.

ONE CANONICAL EXAMPLE: You have a YAML file defining a Deployment with replicas: 3. You run kubectl apply. Kubernetes creates 3 pods. If you then manually delete one pod, the Deployment controller will notice that the actual state (2 pods) no longer matches the desired state (3 pods) and will automatically create a new pod to compensate. Your intent, captured in the file, is always enforced.