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.
kv-gitops applies the WebApp spec, establishing the intended page message and replica count.
- kv-gitops to WebApp m20-platformSSA parent fields
Read the complete visual sequence
- Declare the parent
kv-gitops applies the WebApp spec, establishing the intended page message and replica count.
- Derive the children
The operator applies stable child names with its own field manager and the parent UID owner reference.
- 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.
- New declaration arrives
kv-human applies platform-conflict.yaml against the same WebApp identity.
- Owned field differs
The requested spec.message conflicts with kv-gitops ownership.
- 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.
Multiple passes preserve Deployment UID when the desired child identity remains valid.
- WebApp parent to Reconcile passesdesired state
- Reconcile passes to Deploymentrepeat apply
Read the complete visual sequence
- Repeat without replacement
Multiple passes preserve Deployment UID when the desired child identity remains valid.
- Repair deleted configuration
Deleting the ConfigMap creates drift; another pass recreates current desired page content with a new child UID.
- 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.
- Two sources declare the child
GitOps applies generated Deployment fields independently from the operator.
- Reconciliation conflicts or oscillates
The managers disagree or repeatedly take fields from each other.
- 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
- Server-side apply conflicts
- Operator pattern
- Owner references and garbage collection
- Argo CD automated sync
Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise