Appearance

Build an idempotent operator

Reconcile WebApp intent into stable children and honest status.

What you will understand

  • Trace the host Python operator through each child write.
  • Explain why repeating reconciliation preserves identity.
  • Distinguish processed generation from workload readiness.

Builds on: CRDs, schemas, and conversion

Mental model: write a comparison, not an installation script

The teaching operator reads WebApps in the named disposable namespace and derives a ConfigMap plus a Deployment for each one. The ConfigMap contains index.html from spec.message; the Deployment uses spec.replicas and mounts that ConfigMap into nginx’s document directory. Stable child names come from the WebApp name. A second reconcile pass finds the same intended children rather than creating another uniquely named web server.

Idempotence means repeated reconciliation converges to the same intended resource relationships despite retries and partial success. It does not require every HTTP request to be absent or every resourceVersion to remain unchanged. The useful identity check is that a Deployment UID stays stable when no replacement is required. Status updates and field-management metadata can still change. A controller should avoid unnecessary writes where practical, but correctness cannot depend on receiving exactly one trigger.

WebApp intent becomes ordinary resources

Deployment controllers and kubelets create ready Pods; the custom controller does not synchronously start containers.

Flow viewStep 1 of 3
Derive desired childrenThe operator maps one WebApp to stable ConfigMap and Deployment names.. WebApp m16, replicas + page message, idle. Python reconcile, Compute desired children, active. ConfigMap m16, index.html from message, idle. Deployment m16, replicas from spec, idle. nginx Pods, Normal Deployment rollout, idleWebApp m16: replicas + page message
WebApp m16replicas + page messageContext
Python reconcile: Compute desired children
Python reconcileCompute desired childrenIn focus
ConfigMap m16: index.html from message
ConfigMap m16index.html from messageContext
Deployment m16: replicas from spec
Deployment m16replicas from specContext
nginx Pods: Normal Deployment rollout
nginx PodsNormal Deployment rolloutContext
WebApp m16replicas + page messageContext
Python reconcileCompute desired childrenIn focus
ConfigMap m16index.html from messageContext
Deployment m16replicas from specContext
nginx PodsNormal Deployment rolloutContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Child write fails midway
Derive desired children

The operator maps one WebApp to stable ConfigMap and Deployment names.

Read the complete visual sequence
  1. Derive desired children

    The operator maps one WebApp to stable ConfigMap and Deployment names.

  2. Apply owned fields

    It checks owner identity and applies fields with kv-webapp-operator without forcing competing ownership.

  3. Delegate workload behavior

    Deployment controllers and kubelets create ready Pods; the custom controller does not synchronously start containers.

Child write fails midway

Successful writes are not rolled back as one API transaction.

  1. ConfigMap exists

    The first child write committed successfully.

  2. Deployment apply fails

    A permission or field ownership error blocks the next operation.

  3. Next pass resumes

    Fix the cause and rerun reconciliation; the existing correctly owned ConfigMap is reused.

About this model

The downloadable controller polls through kubectl and intentionally omits production informer and queue machinery.

Try the mechanism with your own inputs
The replica target already agreesDesired and observed replica targets agree. Repeating reconciliation preserves the same stable specification. The lab operator may still apply an unchanged object.. WebApp desired, Replicas: 1, active. Operator, Target agrees, ready. Deployment target, spec.replicas: 1, readyWebApp desired: Replicas: 1
WebApp desiredReplicas: 1In focus
Operator: Target agrees
OperatorTarget agreesReady
Deployment target: spec.replicas: 1
Deployment targetspec.replicas: 1Ready
WebApp desiredReplicas: 1In focus
OperatorTarget agreesReady
Deployment targetspec.replicas: 1Ready
The replica target already agrees

Desired and observed replica targets agree. Repeating reconciliation preserves the same stable specification. The lab operator may still apply an unchanged object.

apiVersion: labs.kv.example/v1alpha1
kind: WebApp
metadata:
  name: example
  namespace: kv-lab
spec:
  replicas: 1
  message: Hello from the control loop
# Child Deployment.spec.replicas target: 1

Walkthrough: each write is its own commit boundary

Read operator.py from the m16 download before running it. It calls kubectl with an explicit context and namespace, verifies the disposable cluster, lists WebApps, computes desired child objects, refuses to adopt an existing unrelated child, and applies each child using manager kv-webapp-operator. It then reads the Deployment and patches the WebApp status subresource with observedGeneration and readyReplicas. Authentication and TLS are delegated to kubectl rather than reimplemented in Python.

These operations are not one transaction. A crash can leave the ConfigMap created before the Deployment exists, or both children present before status is updated. The next pass must reuse the successful partial work. When a child exists under the expected name, the operator checks owner identity before applying it; equal names do not establish permission to take over somebody else’s resource. SSA conflicts also remain visible because the example deliberately does not force ownership.

Identity is stable while observation advances

Status records the desired generation processed and the ready count actually observed, which may still be zero.

Lifecycle viewStep 1 of 3
Repeat the same intentionAnother pass applies the same child name and ownership instead of creating a replacement Deployment.. WebApp generation, Desired generation G, idle. Deployment UID D, Stable generated child, active. Reconcile pass, Read current Deployment status, idle. WebApp status, observedGeneration + readyReplicas, idleWebApp generation: Desired generation G
WebApp generationDesired generation GContext
Deployment UID D: Stable generated child
Deployment UID DStable generated childIn focus
Reconcile pass: Read current Deployment status
Reconcile passRead current Deployment statusContext
WebApp status: observedGeneration + readyReplicas
WebApp statusobservedGeneration + readyReplicasContext
WebApp generationDesired generation GContext
Deployment UID DStable generated childIn focus
Reconcile passRead current Deployment statusContext
WebApp statusobservedGeneration + readyReplicasContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Readiness has not converged
Repeat the same intention

Another pass applies the same child name and ownership instead of creating a replacement Deployment.

Read the complete visual sequence
  1. Repeat the same intention

    Another pass applies the same child name and ownership instead of creating a replacement Deployment.

  2. Sample workload status

    The operator reads readyReplicas after applying; rollout may still be progressing.

  3. Report processed generation

    Status records the desired generation processed and the ready count actually observed, which may still be zero.

Readiness has not converged

Processed desired state is different from an available application.

  1. New generation accepted

    The WebApp spec changes to request two replicas.

  2. Controller processes generation

    The operator applies the new count and records its observation before the new Pod is ready.

  3. Status is honest but incomplete

    observedGeneration can match current generation while readyReplicas is below desired; run another pass after rollout.

About this model

The minimal API lacks a Ready condition; sampled readyReplicas may reflect an earlier Deployment generation and does not prove current-revision readiness.

The custom resource is a compact API for desired behavior. Normal Kubernetes controllers still implement Deployment rollout, replica replacement and Pod startup. This is why the operator can stay small while the application lifecycle remains asynchronous.

apiVersion: labs.kv.example/v1alpha1
kind: WebApp
metadata:
  name: m16
  namespace: kv-lab
  labels:
    lab: m16
spec:
  replicas: 2
  message: repeated-reconcile-is-safe
# Run after installing the m16 CRD and resources.
python3 operator.py --once
kubectl --context kind-kv-lab -n kv-lab rollout status deployment/m16 --timeout=180s
kubectl --context kind-kv-lab -n kv-lab get deployment m16 -o jsonpath='{.metadata.uid}{"\n"}'
python3 operator.py --iterations 3 --interval 1
kubectl --context kind-kv-lab -n kv-lab get deployment m16 -o jsonpath='{.metadata.uid}{"\n"}'
kubectl --context kind-kv-lab -n kv-lab get webapp m16 -o yaml

Practice: observe convergence twice

Run the m16 local exercise. Expect a ConfigMap and Deployment owned by the WebApp, then ready nginx Pods after normal rollout. Compare the child UID before and after repeated reconciliation. Change spec.replicas to two, run the operator again, and wait for the Deployment’s rollout before checking WebApp status. Because status is sampled during a reconcile pass, run one more pass after readiness if you want its readyReplicas observation to catch up.

Inspect the actual mounted page with a request from a Pod or a local port-forward. ConfigMap volume updates propagate asynchronously; this example does not restart Pods by hashing the ConfigMap into the Pod template. A successful API patch therefore does not prove every server has already observed new content. Document the intended refresh behavior if you extend the API to applications that read configuration only once at startup.

Pitfalls: understand the deliberate omissions

This operator is a host-run, dependency-free polling demonstration. It does not provide informer caches, a rate-limited workqueue, multi-replica leader election, rich conditions, admission defaulting or external-resource finalizers. It uses the host’s Kubernetes credentials, so its safety checks are not a substitute for production least-privilege RBAC. It exits on an error rather than isolating every resource failure into a robust queue. These boundaries make the mechanism inspectable and identify the engineering needed before operating a shared platform.

Inspect status after the final reconcile pass rather than treating the first printed success line as a readiness assertion. The process can successfully apply both children while the Deployment controller is still starting its first Pod. Its sampled readyReplicas can also describe Pods from an earlier Deployment generation. A production Ready condition must check the child’s observed generation and relevant rollout conditions as well as the parent generation; this minimal status does not prove current-revision readiness.

Check your understanding

The operator crashes after creating the ConfigMap. Should the next run delete it and start over?

No. With a stable name and matching owner UID, the next pass can reuse or update it, create the missing Deployment, and refresh status. Deleting successful partial work creates unnecessary disruption and can be unsafe for resources holding data.

Next, delete a generated child and observe repair. Then delete the parent and distinguish garbage collection from active operator cleanup.

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.