Imperative Operations vs. Declarative Reconciliation

Hello! Last lesson, you built an image and saw that a tag can point to new content after a rebuild. An image tells a container runtime what to run; it does not, by itself, ensure that an application keeps running.

In this lesson, you’ll distinguish imperative operations from declarations of desired state, then see how Kubernetes controllers work to close the gap between what you requested and what is actually running. This is a core KCNA distinction and the foundation for the local Kubernetes labs ahead.

An action is not the same as an enduring request

Suppose you need three copies of a web application. One approach is to start three containers and, whenever one disappears, start another. You are responsible for noticing the failure and issuing the next command. Those are imperative operations: instructions to perform particular actions.

A different approach is to record “the desired replica count is three” in a system that continually observes the application. If only two copies exist, that system requests another. If all three exist, it need not change anything. The declaration states what condition you want maintained, rather than enumerating every action required to maintain it.

Kubernetes supports both ways of managing objects. An imperative command can directly create or change a live object; a declarative workflow can submit configuration from a file. There is also a middle case worth recognizing for the exam: putting an object definition in a YAML file does not automatically make the operation declarative. kubectl create -f web.yaml specifies the action create; kubectl replace -f web.yaml specifies replace. By contrast, kubectl apply -f web.yaml uses the configuration to determine the changes needed for the object.

For now, treat these commands as illustrations, not commands to run yet—you will create a Kubernetes cluster in the next lesson:

kubectl create deployment web --image=nginx
kubectl scale deployment web --replicas=3
kubectl apply -f web.yaml

The first two commands explicitly request an operation on the live cluster. The third asks Kubernetes tooling to bring the object’s configuration into line with a file. Crucially, all three can ultimately set up or modify a Kubernetes Deployment, whose controllers then work to maintain its requested replica count. An imperative way of submitting a change does not switch off Kubernetes reconciliation.

Reconciliation: what happens after the request

A controller is a control loop. It repeatedly compares the state it wants with the state it observes and, where possible, makes or requests changes that reduce the difference. The thermostat analogy in the Kubernetes documentation is useful because it separates setting a target from continuously responding to changing conditions.

Here is the distinction in three parts:

• Desired state is the target recorded in Kubernetes objects—for example, a Deployment requesting three replicas. An object’s spec generally expresses what was requested.
• Observed state is what the cluster currently reports. An object’s status can report progress toward the target, but it may lag behind changes.
• Reconciliation is the controllers’ ongoing work to reduce the difference. It continues after your kubectl command has exited.

That last point matters. kubectl apply is not a process that stays running and watches your local YAML file. It submits changes when you invoke it. Kubernetes controllers subsequently respond to the desired state stored in the cluster. If you edit the local file but do not submit it again, the cluster does not learn about the edit.

Follow one desired state through a failure

Watch this short visual example of a Deployment requesting multiple copies of an application:

Imagine a Deployment with a requested replica count of three. The simplified observations might look like this:

The controller does not need you to rerun the command that originally set the replica count. It responds because the target still exists. Conversely, if you deliberately change that target to two, creating a third replacement would no longer be the right response.

Reconciliation is not instant success. A replacement Pod might remain unable to run if the cluster lacks capacity or its image cannot be retrieved. The requested count can remain three while the observed, healthy count is lower. This is why KCNA questions may ask both what Kubernetes tries to maintain and what it can currently report.

See the missing piece with Docker

Your existing Docker setup gives you a quick contrast. Run these commands locally; they do not require Kubernetes. The Alpine image should already be familiar from your image-building lab.

docker run -d --name kcna-manual alpine:3.21 \
  sh -c 'while true; do sleep 30; done'

docker ps --filter name=kcna-manual --format '{{.Names}} {{.Status}}'
docker rm -f kcna-manual
docker ps --all --filter name=kcna-manual --format '{{.Names}} {{.Status}}'

The first check should show the running container; the last should return no matching container. In this experiment, no independent controller holds a request to maintain kcna-manual, so removing it does not produce a replacement. The experiment does not mean Docker can never restart a container or participate in an orchestrated system. It isolates the missing element: an enduring desired state with something watching and acting on it.

There is a useful distinction from Linux administration here. An Ansible task declaring that a service should be started can bring a host into the requested condition when the playbook runs. Kubernetes controllers continue reconciling after the client that submitted the request is gone. Both can use desired-state language, but their observation and correction schedules differ.

Two contrasts to keep separate

First, imperative versus declarative object management describes how you express and submit a change. Direct commands are convenient for exploration and one-off operations. Configuration files can be reviewed and stored in version control, which makes an intended change easier to reproduce. The documentation cautions against mixing management techniques for the same object: for example, a live change to a replica count can conflict with a later application of a file that specifies a different count.

Second, one-time submission versus ongoing reconciliation describes what happens afterward. A command such as kubectl scale may be imperative, yet it changes the desired replica count that controllers will then maintain. kubectl apply is declarative object management, yet it runs only when invoked; the controllers, not the local file or the kubectl process, perform ongoing reconciliation.

One more boundary is important: ordinary kubectl apply -f creates or updates objects described by the file. Simply removing an object’s YAML from a directory does not, by itself, tell the cluster to delete that object. Deletion requires an explicit operation or additional pruning or automation. This keeps “declarative” from becoming shorthand for “Kubernetes somehow detects every local change.”

Key takeaways

Imperative operations specify actions; declarative configuration specifies an intended state. Kubernetes controllers then compare desired and observed state and keep working to reduce discrepancies, even after the submitting command finishes. A YAML file can still be used imperatively, and an imperative command can still set a target that Kubernetes reconciles.

Next, you’ll create a local Kubernetes cluster with kind and verify access using kubectl. That will give you a place to observe these ideas rather than only reason about them.