Project challenges / verified progress
Beacon: give it somewhere to live

The engineering notebook

Trust the loop

What changes when software is run by a control loop instead of a person?

Loading Vault account...
Phase 1 — Learn the control plane

Step 01 of 06

Understand the idea

A container image holds the files needed to run a program, but it does not run or manage that program by itself. Kubernetes runs containers, restarts them after failures, and helps route traffic to them.

DECLARE, OBSERVE, RECONCILE01Desired stateobjects in the API02Observed statewhat nodes report03Controllercloses the gap04Statustruth written back
Kubernetes is not a command runner. You write desired state to the API server; controllers compare that state with the cluster and keep nudging reality back into shape.
Step 01

Key technical ideas

The API server is the source of truth

Kubernetes stores the instructions you submit in its API server. For example, a Deployment describes how many copies of Beacon should run. kubectl apply sends those instructions to the API server, which checks and stores them. Controllers read the instructions and report the current status.

Controllers keep the cluster in the desired state

A controller repeatedly checks whether the cluster matches the instructions you submitted. If something is missing, it takes action. For example, the Deployment controller creates a ReplicaSet, and the ReplicaSet creates Pods. This repeated check and repair process is called reconciliation.

Describe the result you want

An imperative command tells Kubernetes to do one action now, such as start a container. A declarative configuration describes the result you want, such as keeping three copies running. Kubernetes keeps working toward that result if a Pod stops or a machine fails. You describe the desired result in a configuration file.

Orchestration trades simplicity for repair

Running one container with Docker is simpler to set up. Kubernetes adds features for running containers across machines, updating them, restarting failed copies, and controlling access. It also adds new parts to learn and troubleshoot, including scheduling, labels, health checks, and permissions.

A thermostat is a control loop
desired: 21 C
observed: 18 C
action: heat
observed: 21 C
action: stop heating

Nobody holds a switch until the room is warm. The thermostat keeps comparing measured temperature with desired temperature. Kubernetes does the same with pods, endpoints and volumes, except the room sometimes says ImagePullBackOff.

Imperative and declarative operations

QuestionImperativeDeclarative

What you say

Start this now

Keep this true

Common tool

docker run

kubectl apply

After failure

Human repeats it

Controller repairs it

Stored where

Shell history, maybe

Kubernetes API

Debug focus

The command output

Object status and events

Technical terms used at work

  • Desired state — The object spec you submit to the Kubernetes API.

  • Observed state — What controllers and nodes report is actually happening.

  • Reconciliation — Repeatedly closing the gap between desired and observed state.

  • Controller — A process that watches the API and takes action for one kind of object.