The Declarative Model and the Desired State

Declarative model

The declarative model and desired state are at the core of how Kubernetes operates. They operate on three basic principles:

• Observed state

• Desired state

• Reconciliation

Observed state is what we have, desired state is what we want, and reconciliation is the process of keeping observed state in sync with desired state.

Terminology: We use the terms actual state, current state, and observed state to mean the same thing — the most up-to-date view of the cluster.

Working of declarative model

In Kubernetes, the declarative model works like this:

1. We describe the desired state of an application in a YAML manifest file

2. We post the YAML file to the API server

3. It gets recorded in the cluster store as a record of intent

4. A controller notices the observed state of the cluster doesn’t match the new desired state

5. The controller makes the necessary changes to reconcile the differences

6. The controller keeps running in the background, ensuring observed state matches desired state

Let’s have a closer look.

We write manifest files in YAML that tell Kubernetes what an application should look like. We call this desired state, and it usually includes things such as which images to use, how many replicas, and which network ports.

Once we’ve created the manifest, we post it to the API server where it’s authenticated and authorized. The most common way of posting YAML files to Kubernetes is with the kubectl command-line utility.

Once authenticated and authorized, the configuration is persisted to the cluster store as a record of intent.

At this point, the observed state of the cluster doesn’t match our new desired state. A controller will notice this and begin the process of reconciliation. This will involve making all the changes described in the YAML file and is likely to include scheduling new Pods, pulling images, starting containers, attaching them to networks, and starting application processes.

Once reconciliation is completed, observed state will match desired state, and everything will be OK. However, the controllers keep running in the background, ready to reconcile any future differences.

Declarative model vs. imperative model

It’s important to understand that what we’ve described is very different from the traditional imperative model:

• The imperative model requires complex scripts of platform-specific commands to achieve an end-state

• The declarative model is a simple platform-agnostic way of describing an end state

Kubernetes supports both but prefers the declarative model. This is because the declarative model integrates with version control systems and enables self-healing, autoscaling, and rolling updates.

A closer look: Example scenario

Consider a couple of simple declarative examples.

Assume we’ve deployed an app from a YAML file requesting 10 replicas. If a node running two of the replicas fails, the observed state will drop to 8 replicas and no longer match the desired state of 10. That’s OK, a controller will see the difference and schedule 2 new replicas to bring the total back up to 10.