driftdetection

Overview ¶

Package driftdetection implements provider-agnostic, per-field drift ownership for Crossplane managed resources.

It is a decorator over crossplane-runtime's TypedExternalConnector and contains NO per-resource logic: managed resources are inspected through fieldpath's unstructured projection, so one implementation serves every managed resource type in both API scopes.

Semantics ¶

The configuration is a peer of forProvider:

spec:
  driftDetection:
    mode: enabled          # enabled (default) | warn | disabled
    ignore:
      - paths:
          - forProvider.description

The modes are:

• enabled: detect and correct drift. Paths under ignore are owned by someone else: seeded from spec on create, then neither compared nor written from spec.
• warn: detect drift, report it on the DriftDetected condition, do not correct it. The adoption mode: observe what actually drifts before deciding what to hand over.
• disabled: neither detect nor correct.

A resource with no driftDetection block behaves exactly as it did before the field existed: the decorator reads the (absent) configuration, delegates, and touches nothing.

Why an ignored field is substituted rather than skipped ¶

Several controllers in this provider build their update request from spec.forProvider as a whole. A field merely skipped in the comparison would still be written from spec the next time any sibling field changed, which reverts the field's real owner. So an ignored path is substituted: the value observed on the external resource is written over the spec value before the resource is compared and before the update request is built. The field then compares equal by construction, and the update carries the value its real owner set.

This relies on a resource's observation type carrying a counterpart for the ignored field under the same name: forProvider.x has a counterpart at status.atProvider.x, and the controller fills it in on every observation.

Ignore-path eligibility ¶

Ignore paths are default-deny. A path is accepted only when every one of the following holds, and is otherwise rejected outright by ReadConfig:

• it is not identity-participating (identityDenylist). GitHub addresses every resource of this provider under its organization, so the org field and its reference and selector companions are denied: substituting one would re-address the object rather than retarget a value. No other forProvider field takes part in an external identifier; each resource is addressed by its external-name, which is not a spec field.
• it names a real field under spec.forProvider, checked by reflecting over the resource's own generated type. A name that happens to resolve under status.atProvider is not itself a forProvider field, and accepting it would capture an observed value that apply's lenient unstructured-to-typed conversion then drops: no error, and the field is never substituted.
• it has a counterpart in status.atProvider on the resource's own type. A write-only field has no observed value to carry forward.
• it is listed in eligibleIgnorePaths: the controller actually populates that counterpart on Observe. This provider's status.atProvider is deliberately near-empty and most observation fields are declared but never written, so a field that merely has a counterpart in the type would be observed as absent and keep its seed value, and the update would still send the spec value. eligibleIgnorePaths is empty: no controller mirrors any forProvider field into status.atProvider today, so every ignore path is rejected. A path becomes eligible only together with the controller change that populates its counterpart.

A path naming any ineligible class is rejected outright by ReadConfig — never silently skipped, and never partially applied alongside the paths that were fine. mode: warn and mode: disabled need no ignore paths and are fully available.

Freshness and race safety ¶

crossplane-runtime constructs one external client per reconcile (Connect at the top of Reconcile, Disconnect deferred to its end) and calls Observe strictly before Update on the same in-memory object. This decorator therefore captures the observed values of ignored paths into per-reconcile state during Observe, and Update consumes that snapshot instead of re-reading status.atProvider.

That ordering is what makes the substitution safe:

• The values written on update are from this reconcile's observation, not a previous one. Re-reading status.atProvider in Update would read whatever the object happens to carry, which for any code path that does not repopulate it is last poll's value.
• Update fails closed if no observation was captured. Falling back to the spec value would revert the field's real owner, which is the exact outcome the ignore list exists to prevent.
• Substitution always happens on a deep copy, so the reconciler's managed resource — and any cache it was decoded from — is never mutated, and there is no interaction with ResourceLateInitialized persistence.

A lost-update window remains between the observation and the mutation: if the external owner changes the field in that interval, the update writes the value observed a moment earlier and the owner reasserts on its next pass. It cannot be closed by a read-modify-write client. The window only opens during updates that were going to happen anyway — drift confined to ignored paths never triggers an update.