A custom-resource definition adds an API type to a Kubernetes cluster. A custom resource cannot be admitted until that definition is established, and a controller may not be ready to reconcile it immediately afterward. GitOps synchronization order can sequence objects, but an annotation that places a definition earlier does not prove the corresponding controller is healthy or that a newly changed schema is compatible with existing instances.
Make this comfortable
GitOps rollout order: install API definitions before dependent objects
Operational decision
A billing operator upgrade introduces a new InvoiceQueue field. Put the definition in an earlier synchronization wave, wait for it to become Established, and roll the controller with a compatibility check before applying resources that use the field. The YAML fragment shows annotations on two resources; it is not a full definition or instance. In a disposable cluster, sync the old resource under the new definition, then the new resource under both old and new controller versions if the upgrade permits overlap. Observe reconciliation status and a synthetic queue operation before continuing application rollout. If the controller fails, stop the sync and retain the old working objects; removing an API definition can delete access to every instance and may destroy data depending on the environment. Record the intended reverse order for rollback, including whether the old controller understands the new field.
kind: CustomResourceDefinition
metadata:
name: invoicequeues.billing.aitrove.test
annotations:
argocd.argoproj.io/sync-wave: '-1'
---
kind: InvoiceQueue
metadata:
name: payout-queue
annotations:
argocd.argoproj.io/sync-wave: '1'Cost and verification
More synchronization stages slow deployment and increase the number of intermediate states that must be observed. They also prevent a fast application rollout from outrunning its API and controller dependencies. Watch API establishment, controller availability, and reconciliation errors separately. A green GitOps sync can still leave a business queue stuck if its controller reports Ready but cannot process the new field. Keep both schema and on-disk compatibility in the rollback plan.
Common Mistakes
- Do not create a new custom resource before its definition is established.
- Do not treat wave order as proof that the controller processed the instance.
- Do not delete a definition to roll back one bad instance.
Connected lessons
- DevOps: delivery, infrastructure, and reliable operations
- GitOps reconciliation: desired state and drift
- Cluster upgrade drill: preserve a path through each version step
- Kubernetes admission policy: reject an unsafe workload before scheduling
- Release evidence: tie one deployed digest to one approval decision
Practice and check
Advanced follow-up
GitOps operating-boundary follow-up
devops
operations