Kubernetes / Basic: objects and execution boundaries / Lesson 1

Architecture and declarative reconciliation

Trace desired state through API storage, controllers, scheduling, and node execution without mistaking acceptance for a working service.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Explain the model, assumptions, and boundaries of architecture and declarative reconciliation.
Interpret both examples and distinguish declared intent from established evidence.
Diagnose the listed failures and justify the worked recovery decisions without executing cluster operations.

Define the orchestration problem

Kubernetes coordinates workloads across machines using declared objects and ongoing control loops. It can replace failed instances and manage placement, but cannot infer whether a business transaction is correct. Applications still own data consistency, idempotency, and meaningful health behavior. Begin with the boundary between a requested object and an observed user outcome. A successful API response means a request passed the relevant processing, not that a container started or a customer received a valid result. This course teaches those boundaries without creating, contacting, or administering a cluster.

Separate control plane from nodes

The API server exposes the Kubernetes API; etcd stores cluster state; controllers observe objects and act toward desired conditions; the scheduler assigns suitable unscheduled Pods. On a node, kubelet coordinates Pod execution through the container runtime and reports observations. Networking components and plugins provide important data-plane behavior. These roles may be packaged differently by a distribution or managed service. The first diagram describes responsibilities rather than a guaranteed physical topology. Control-plane access, node health, and application reachability can fail independently, so choose evidence from the layer that matches the symptom.

text Conceptual component responsibilities

intent -> API server -> stored objects
controllers -> compare desired and observed state
scheduler -> choose a feasible node
kubelet + runtime -> execute and report
network implementation -> carry application traffic

Arrows describe related responsibilities, not a synchronous transaction or exact physical topology. The diagram does not imply all implementations use one networking component.

Reason in desired and observed state

A controller repeatedly compares intent with observations and takes bounded actions. There is usually a delay between changing intent and observing convergence. Status is evidence produced by components and may lag reality. The second simulation models a controller discovering a deficit of two replicas; it does not create them. Real reconciliation also needs retries, ownership, conflict handling, and failure reporting. Do not assume that every loop can undo an external side effect or that repeated action is automatically safe. A well-designed controller converges without endlessly duplicating work.

python Harmless reconciliation arithmetic

desired = 5
observed = 3
missing = max(0, desired - observed)
print(missing)
print("plan only; no resources created")

Expected output

2
plan only; no resources created

The controller model sees a deficit of two. Real availability and ownership checks are intentionally outside this pure in-memory calculation.

Distinguish availability of each boundary

Existing workloads may continue while the API server is unavailable, but new scheduling and control actions can be impaired. A healthy API does not prove nodes have capacity or that Services route correctly. Identify what is cached, what requires fresh control-plane communication, and what depends on an external provider. Record time, context, namespace, object identity, and component when interpreting evidence. Avoid diagnosing a production application from an unrelated local kubeconfig context. No context discovery command is executed here; all records and examples are synthetic teaching material.

Use explicit API and version assumptions

Examples use stable APIs such as v1, apps/v1, batch/v1, rbac.authorization.k8s.io/v1, and networking.k8s.io/v1. Support, feature gates, admission policy, plugins, and defaults still depend on the installed versions. The official release page reviewed on 2026-10-25 lists maintained minor branches 1.37, 1.36, and 1.35; this dated statement must be rechecked before planning an environment. Read the deprecation and version-skew policies instead of copying an old manifest. YAML syntax checks in this course do not establish server acceptance, provider support, security, or workload correctness.

Common errors and fixes

Accepted means deployed

Why it happens: API acceptance was confused with observed convergence.
How to fix it: Inspect controller progress and the user-facing contract separately.
Prevent it next time: Define completion evidence beyond request success.

A healthy API hides an application outage

Why it happens: Control-plane health replaced data-plane evidence.
How to fix it: Trace node, endpoint, network, and application behavior.
Prevent it next time: Separate component health indicators and owners.

An old manifest uses an unavailable API

Why it happens: Version and deprecation assumptions were unchecked.
How to fix it: Use supported API versions and review changed semantics.
Prevent it next time: Track API inventory and compatibility before upgrades.

Check your understanding

1. The API accepts a Deployment but no Pod is ready. What has actually succeeded?

Show worked solution

Only the relevant API request processing is established. Check controller observation, scheduling, image and startup state, readiness, and routing before claiming service success. These stages may fail independently, and a client response from the API does not exercise the application.

2. Desired replicas are four and observed replicas six. What does the simple missing-replica model return, and what does it omit?