Enhance management policy options

[lsviben]

What problem are you facing?

Management policies (managementPolicies) define which actions Crossplane takes on an external resource using a set of primitive actions: Observe, Create, Update, Delete, LateInitialize, and * (all). These primitives intentionally mirror the methods of the ExternalClient interface.

There is a real and well-documented need (see #872, #864, #873, crossplane/crossplane#6694) for richer semantics around these actions — specifically:

• "Must create": Fail if the external resource already exists instead of silently adopting it
• "Orphan" shorthand: A convenient way to express ["Observe", "Create", "Update", "LateInitialize"] for users migrating from deletionPolicy: Orphan

PR #873 attempted to solve "must create" by adding a MustCreate ManagementAction, and PR #864 added an Orphan ManagementAction. Both were reverted before v2.2 because adding flavors of existing primitives has several problems:

1. Combinatorial explosion: Every new action variant multiplies the supported policy combinations in defaultSupportedManagementPolicies(), which is already 15 entries.
2. • loses meaning: If MustCreate exists alongside Create, does * include MustCreate? What about Orphan?
3. Composition breaks down: Combining Orphan (no Delete) with MustCreate (strict Create) would require yet another compound action or careful exclusion rules.
4. Primitives should map to ExternalClient methods: Observe, Create, Update, Delete are clean primitives. MustCreate and Orphan are behavioral modifiers, not new operations.

How could Crossplane help solve your problem?

Find a way to enhance managementPolicies with behavior modifiers.

[lsviben]

BTW we could use this opportunity to reconsider what to do with LateInitialize which is also more of a behavioral modifier then a primitive.

[bobh66]

Related discussion here: crossplane-contrib/provider-helm#328

[lsviben]

Sorry @bobh66 , couldnt get to this sooner. 🙏 .

I have checked the options we have and I see a few paths we can take.

Management Policies options

A: List->Map - Breaking change

This follows your proposal to change the managementPolicies from a list to a map such as

   managementPolicies:
    observe: true   # true/false
    create: required  # true/false/requried
    update: false  # true/false
    delete: false  # true/false

While the API hear looks clean the problem is we would need v3 to do this change as a breaking change.

We could though maybe deprecate managementPolicies and add a field managementPolicy (or similar name) and add that there. And then when v3 comes we do the final switch.

B: Add an options field

Add managementOptions in which we can add modifiers to the primitives(Observe, Create, Update, Delete) behavior of managementPolicies.

So we would have something like:

managementPolicies: ["Observe", "Create", "Update"]
managementPoliciesOptions:
  mustCreate/importExisting: true
  lateInitialize: false # - this would be a proper place for LateInitialize at one point

Management Policies Aliases

Regarding making aliases instead of the full list/map/options I think we can wait with this until we figure out the above.

My take

I think its easier to go with B and not making more breaking changes, v3 is not even on the horizon yet so its unclear when we would do the proper switch + I think that the option with making the managementPolicy deprecated and making folks use the new struct is more annoying/difficult then adding a managementOptions field for folks that really need the enhanced capability (which may not be a big percentage)