Appearance

Capstone: GitOps and an operator

Keep custom-resource intent and generated-child ownership separate.

What you will understand

  • Identify the GitOps and operator field-management boundaries.
  • Demonstrate conflict, repeated reconciliation and drift repair.
  • Verify child removal through parent ownership.

Builds on: Ownership and failure recovery, GitOps and drift reconciliation, Capstone: recover stateful data

Mental model: each controller needs a clear declaration boundary

The final capstone has two declarative roles. GitOps, modeled locally by the kv-gitops field manager, owns the WebApp spec. The Python operator reads that intention and owns fields on the generated ConfigMap and Deployment as kv-webapp-operator. The operator also reports observed status on the WebApp’s status subresource. GitOps should not independently declare the generated children’s replica count or page contents, because doing so would create competing sources of intent.

These are different forms of ownership. managedFields records which actor manages particular API fields. ownerReferences records the lifecycle relationship between each generated child and the WebApp UID. Neither is a universal permission grant; RBAC and admission still govern requests. A controller can be authorized yet encounter a field conflict, or own fields on a child whose lifecycle owner is a separate parent object. Name each boundary when explaining a failure.

GitOps owns intention; operator owns implementation

Status describes processed generation and observed ready count; GitOps acceptance is not synchronous application readiness.

Ownership viewStep 1 of 3
Declare the parentkv-gitops applies the WebApp spec, establishing the intended page message and replica count.. kv-gitops, Owns WebApp spec, idle. WebApp m20-platform, replicas + message, active. kv-webapp-operator, Owns child fields, idle. Deployment + ConfigMap, Owner reference to WebApp UID, idle. WebApp status, Operator observations, idle. kv-human, Conflicting parent declaration, idlekv-gitops: Owns WebApp spec
kv-gitopsOwns WebApp specContext
WebApp m20-platform: replicas + message
WebApp m20-platformreplicas + messageIn focus
kv-webapp-operator: Owns child fields
kv-webapp-operatorOwns child fieldsContext
Deployment + ConfigMap: Owner reference to WebApp UID
Deployment + ConfigMapOwner reference to WebApp UIDContext
WebApp status: Operator observations
WebApp statusOperator observationsContext
kv-human: Conflicting parent declaration
kv-humanConflicting parent declarationContext
kv-gitopsOwns WebApp specContext
WebApp m20-platformreplicas + messageIn focus
kv-webapp-operatorOwns child fieldsContext
Deployment + ConfigMapOwner reference to WebApp UIDContext
WebApp statusOperator observationsContext
kv-humanConflicting parent declarationContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Human conflicts on parent spec
Declare the parent

kv-gitops applies the WebApp spec, establishing the intended page message and replica count.

Read the complete visual sequence
  1. Declare the parent

    kv-gitops applies the WebApp spec, establishing the intended page message and replica count.

  2. Derive the children

    The operator applies stable child names with its own field manager and the parent UID owner reference.

  3. Report a separate observation

    Status describes processed generation and observed ready count; GitOps acceptance is not synchronous application readiness.

Human conflicts on parent spec

A different SSA manager attempts a different message value.

  1. New declaration arrives

    kv-human applies platform-conflict.yaml against the same WebApp identity.

  2. Owned field differs

    The requested spec.message conflicts with kv-gitops ownership.

  3. Conflict preserves the contract

    The script expects rejection; forcing would intentionally change the ownership decision being tested.

About this model

The local GitOps role is modeled by kubectl SSA; a real Argo CD installation is optional.

Walkthrough: the conflict is an expected result

Read platform.yaml, platform-conflict.yaml and capstone-platform.sh from the m20 download. The script installs the same WebApp API used in m16, applies the parent with kv-gitops, runs the operator and waits for the generated Deployment. It then attempts a second SSA declaration using kv-human with a different page message. The expected result is a conflict on a field managed by the declarative owner. The script fails if that conflicting apply unexpectedly succeeds.

Next, the script captures the Deployment UID, repeats reconciliation and checks that UID remains stable. It deletes the generated ConfigMap, runs another pass, and verifies the recovered page data. Finally, it deletes the WebApp and waits for the generated Deployment and ConfigMap to disappear through garbage collection. Each assertion targets a different property: field coordination, idempotent identity, drift repair and lifecycle ownership. Passing one does not imply the others automatically hold.

Repeat, repair, then collect owned children

Removing the WebApp lets garbage collection remove its owned children; the operator does not recreate the absent parent.

Lifecycle viewStep 1 of 3
Repeat without replacementMultiple passes preserve Deployment UID when the desired child identity remains valid.. WebApp parent, Current UID and intent, idle. Reconcile passes, Stable naming + ownership checks, idle. Deployment, UID stable on repeat, active. ConfigMap, Recreated after deletion, idle. Garbage collector, Deletes dependents after parent, idleWebApp parent: Current UID and intent
WebApp parentCurrent UID and intentContext
Reconcile passes: Stable naming + ownership checks
Reconcile passesStable naming + ownership checksContext
Deployment: UID stable on repeat
DeploymentUID stable on repeatIn focus
ConfigMap: Recreated after deletion
ConfigMapRecreated after deletionContext
Garbage collector: Deletes dependents after parent
Garbage collectorDeletes dependents after parentContext
WebApp parentCurrent UID and intentContext
Reconcile passesStable naming + ownership checksContext
DeploymentUID stable on repeatIn focus
ConfigMapRecreated after deletionContext
Garbage collectorDeletes dependents after parentContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
GitOps also owns child fields
Repeat without replacement

Multiple passes preserve Deployment UID when the desired child identity remains valid.

Read the complete visual sequence
  1. Repeat without replacement

    Multiple passes preserve Deployment UID when the desired child identity remains valid.

  2. Repair deleted configuration

    Deleting the ConfigMap creates drift; another pass recreates current desired page content with a new child UID.

  3. Delete the parent intention

    Removing the WebApp lets garbage collection remove its owned children; the operator does not recreate the absent parent.

GitOps also owns child fields

Overlapping declarations undermine the parent-to-implementation boundary.

  1. Two sources declare the child

    GitOps applies generated Deployment fields independently from the operator.

  2. Reconciliation conflicts or oscillates

    The managers disagree or repeatedly take fields from each other.

  3. Restore the boundary

    Remove redundant child declarations and keep the parent API as the shared intention contract.

About this model

The teaching controller manages only Kubernetes resources and supplies no external cleanup finalizer or production HA machinery.

This is the actual desired parent. The provided conflict file uses the same object identity and a different message; it is not a new independent application.

apiVersion: labs.kv.example/v1alpha1
kind: WebApp
metadata:
  name: m20-platform
  namespace: kv-lab
  labels:
    lab: m20
spec:
  replicas: 1
  message: gitops-declared-page
# Run only the platform investigation from the downloaded m20 directory.
bash capstone-platform.sh
# To inspect before the script's final parent deletion, run its early steps manually:
kubectl --context kind-kv-lab -n kv-lab apply --server-side --field-manager=kv-gitops -f platform.yaml
python3 operator.py --iterations 2 --interval 1
kubectl --context kind-kv-lab -n kv-lab get webapp m20-platform -o yaml --show-managed-fields
kubectl --context kind-kv-lab -n kv-lab get deployment m20-platform -o yaml --show-managed-fields

Practice: report four independent observations

Run the m20 local exercise. Keep the parent apply conflict as a successful diagnostic observation rather than adding force-conflicts. Inspect which manager owns spec.message and compare the child’s owner UID with the WebApp UID. Record the Deployment UID before and after repeated reconciliation, the new ConfigMap UID after repair, and the absence of both children after parent deletion. These observations explain precisely what the minimal controller demonstrated.

If you use the manual inspection commands after the full script, they recreate the parent and children for inspection. Delete that parent again when finished so garbage collection can clean them up. The CRD is shared with m16; do not delete it while either module’s resources are still needed. Cleanup of a CRD is a separate cluster-scoped destructive step, even though the host Python process has already exited.

Pitfalls: this is not a hidden production platform

The mandatory capstone does not install Argo CD, provision remote Git credentials, implement external-resource finalizers, run leader election or provide an informer-backed queue. It models the relevant declaration boundary with real SSA and a working small polling controller. A production version needs least-privilege service-account permissions, per-resource error isolation, backoff, conditions, metrics, tested upgrade behavior and appropriate leadership or fencing for its side effects.

For a deliberate extension, connect an optional Argo CD Application to the parent manifest while keeping child resources out of its desired set. Configure self-heal and prune intentionally, then observe what happens when the operator is stopped or the parent changes. GitOps may accept the WebApp while the generated application is unavailable; expose status that lets a user distinguish accepted intent from readiness. Preserve data retention policy before extending this pattern to stateful children.

Check your understanding

GitOps manages WebApp.spec.message. Should it also force the generated ConfigMap data to the same value?

Usually no. The operator derives that ConfigMap from the parent intention and owns the child fields. Declaring both creates redundant competing control. Keep GitOps on the parent API and let the operator reconcile its implementation, with explicit exceptions only when the platform contract requires them.

Your final recovery record should connect cause, ownership, minimal action and verification for all three capstones. Add new failure scenarios one at a time, keeping the evidence and limitations specific to the mechanism actually exercised.

Go to the source

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

Search the book

Search loads when you open it.