[FEATURE] Provide Composition Examples for CF Resource Deletion Ordering via Crossplane Usage

[gergely-szabo-sap]

Context

Spike #221 confirmed that Crossplane's built-in Usage mechanism works for CloudFoundry managed resource deletion ordering without any provider code changes. The team decided to use existing tools (Crossplane Usage resources with Compositions) rather than implementing provider-managed deletion protection.

However, users currently have no reference examples showing how to compose CF managed resources with correct deletion ordering. Without guidance, users must independently discover how to combine Compositions, Usage resources, and composition functions — a non-trivial effort that slows adoption of the recommended approach.

Scope

Provide runnable Composition examples in the provider repository (docs/ or examples/) that demonstrate how to:

1. Compose multiple CF managed resources into a single Composite Resource with correct creation and deletion ordering
2. Use Crossplane Usage resources (or ClusterUsage) to enforce deletion protection between dependent CF resources
3. Use composition functions (function-sequencer, function-deletion-protection) as the recommended approach for automating Usage creation within the composition pipeline

Proposed examples:

• Minimal — Org + Space with manual Usage: An XRD + Composition + Claim that provisions an Organization and a Space, with a manual Usage resource ensuring the Space is deleted before the Organization. Uses function-patch-and-transform only, no function-sequencer. Target audience: users who want the simplest possible example.

• Typical Stack — Org + Space + ServiceInstance + ServiceCredentialBinding: An XRD + Composition + Claim that provisions a full CF application stack (Org → Space → ServiceInstance → ServiceCredentialBinding) with automated deletion ordering via function-sequencer. Deletion order: bindings → instances → spaces → orgs. Demonstrates function-sequencer with enableDeletionSequencing: true and replayDeletion: true. This is the "typical stack" requested in [SPIKE] Investigate Crossplane ResourceUsage Viability for Cross-Resource Deletion Protection #221 (see comment by @sdischer-sap).

• Crossplane v2 Migration Note: A short guide showing the API differences for v1 (apiextensions.crossplane.io/v1alpha1 Usage) vs v2 (protection.crossplane.io/v1beta1 Usage / ClusterUsage), so users can adapt the examples when upgrading.

Each example must include complete, runnable YAML (XRD, Composition, Claim, required Function + Provider references), prerequisites (Crossplane with --enable-usages for v1, or v2 where it is enabled by default; required composition functions installed), and a "Test deletion ordering" section with kubectl delete commands proving that deletion of a "used" resource is blocked. Crossplane v1 vs v2 differences (API group, namespaced vs cluster-scoped, feature flag) must be documented.

All Composition examples must be covered by e2e tests that verify both creation succeeds and deletion ordering is enforced (i.e., deleting a "used" resource is blocked, and proceeds only after dependents are removed).

Out of scope

• Provider-managed Usage (controller-created Usage resources) — deferred per [SPIKE] Investigate Crossplane ResourceUsage Viability for Cross-Resource Deletion Protection #221 decision
• sharedSpaces (cross-composition references) — requires a dedicated spike per [SPIKE] Investigate Crossplane ResourceUsage Viability for Cross-Resource Deletion Protection #221
• Custom ResourceUsage CRD (BTP-provider approach) — not in scope for CF provider

Technical Steps

1. Create examples/compositions/ directory (or docs/ end-user guide section) in the provider repository
2. Implement Example 1 (Org + Space + manual Usage) — start with function-patch-and-transform, add a Usage resource in the Composition
3. Implement Example 2 (full stack + function-sequencer) — install function-sequencer as a prerequisite, configure enableDeletionSequencing: true and replayDeletion: true
4. Write v1 vs v2 migration note — document API group change, Usage vs ClusterUsage, and feature flag differences
5. Add e2e test cases for each example:
   • Apply the Composition and Claim, verify all composed resources reach Ready: true
   • Attempt kubectl delete on a "used" resource — assert deletion is blocked by the Usage webhook
   • Delete the dependent resource — assert the "used" resource deletion now proceeds
6. Integrate the new e2e tests into the existing test suite and CI pipeline so examples are validated on every PR

Workarounds & Alternatives

Today, users must manually encode deletion ordering by carefully ordering resource creation in their Helm charts or Kustomize overlays, and rely on CF API errors when deletion of a resource with dependents is attempted. This is fragile — there is no enforcement at the Crossplane level, and a kubectl delete on an Org while Spaces still exist will succeed at the Crossplane level but fail at the CF API level, leaving resources in an inconsistent state.

An alternative is the BTP provider's custom ResourceUsage CRD, but this introduces provider-owned deletion infrastructure that must be maintained and evolved as Crossplane evolves.

Additional context

• Parent issue: [SPIKE] Investigate Crossplane ResourceUsage Viability for Cross-Resource Deletion Protection #221 (Spike: Deletion Ordering via Crossplane Usage)
• Previous investigation: Spike - [FEATURE] Tracking Usage to ensure ordered deletion #65
• Crossplane Usage design doc
• function-sequencer
• function-deletion-protection

[sdischer-sap]

Thanks @gergely-szabo-sap, great write up!
I am guessing we just created this for now and do not plan to work on it immediately right?
Maybe we can involve @sk31337 here, since he is experienced in writing those user guides.
Would maybe also speed things up since this isn't part of our q2 goals if I remember correctly.

[gergely-szabo-sap]

I have not started working on this. I don't mind if @sk31337 is involved.

[sdischer-sap]

Talked about it in our refinement:
Next Steps: @SatabdiG will get in contact with @sk31337 to see if he has capacity to take this one over. Otherwise we will postpone until q3.

[sk31337]

Looking forward to the collaboration :)