Add support for Orphan management policy

[bobh66]

Description of your changes

Added an Orphan management policy value which maps to ['Observe', 'Create', 'Update', 'LateInitialize'] in order to simplify the migration from deletionPolicy to managementPolicies and facilitate controlled orphaning of resources.

Fixes #6694 (Crossplane)

Tested using provider-kubernetes running a private branch of crossplane-runtime. Created an Object containing a Secret with the managementPolicies: ['Orphan'] and verified that when the Object was deleted the Secret remained.

Docs PR is crossplane/docs#993

Fixes crossplane/crossplane#6694

I have:

• Read and followed Crossplane's contribution process.
• Run earthly +reviewable to ensure this PR is ready for review.
• Added or updated unit tests.
• Linked a PR or a docs tracking issue to document this change.
  - [ ] Added backport release-x.y labels to auto-backport this PR.

Need help with this checklist? See the cheat sheet.

[jbw976]

This looks like a nice convenience policy that streamlines the experience for enabling the orphaning of resources. Thanks @bobh66! just a couple questions

[jbw976]

this was already done in #865, so it's odd to see here again 🤔

[lsviben]

IMO the idea of management policies is that we define primitives like Observe, Create, Update, Delete that clearly state what will be done with the resources. I intentionally didnt put LateInitialize here as its a bit of an outlier and in hindsight should have been a separate feature outside of management policies.

Adding more policies when we can do the same with the existing ones seems the move in the wrong direction. IMO it would just complicate things more. As its not a primitive, but a policy like * which contains more policies it would be another special case that cannot be combined with other policies.

If we really need a simplifier for management policies, maybe we should introduce a separate field:
managementPolicyAlias which would be translated into managementPolicies.

So you could just set managementPolicyAlias: Orphan which would fill in managementPolicies: ['Observe', 'Create', 'Update', 'LateInitialize'].

[bobh66]

@lsviben I don't disagree that adding Orphan is a workaround, but I'm not sure that adding another field is a better solution. deletionPolicy was a simple and clean interface - maybe managementPolicies should have been a map instead of a list, which would have made it easier to convert from deletionPolicy, and would also make it easier to do things like mustCreate:

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

[lsviben]

@lsviben I don't disagree that adding Orphan is a workaround, but I'm not sure that adding another field is a better solution. deletionPolicy was a simple and clean interface - maybe managementPolicies should have been a map instead of a list, which would have made it easier to convert from deletionPolicy, and would also make it easier to do things like mustCreate:

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

In hindsight and with the context we have today, maybe it would be easier. Although I am wondering if there would be even more things popipng up along with required.

But we should work with what we have today unless we want to make breaking changes. I just added some propositions that came to my mind how to overcome these issues without making changes to the managementpolicies API itself.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new ManagementAction value "Orphan", exposes it in v1, and updates policy resolution and reconciler checks to treat Orphan as a valid action for create/update/late-initialize flows; tests expanded to cover Orphan behavior and a test name typo was fixed.

Changes

Cohort / File(s)	Summary
API Constants apis/common/policies.go, apis/common/v1/policies.go	Adds ManagementActionOrphan constant and updates the kubebuilder enum validation to include "Orphan"; exposes the constant in the v1 API.
Policy Evaluation Logic pkg/reconciler/managed/policies.go	Extends default supported policies to include Orphan and updates ShouldCreate, ShouldUpdate, and ShouldLateInitialize checks to accept Orphan alongside Create/Update/LateInitialize/All policies.
Test Coverage pkg/reconciler/managed/reconciler_legacy_test.go, pkg/reconciler/managed/reconciler_modern_test.go	Adds multiple test cases validating reconciliation behavior under the Orphan management action (create/update/late-init paths) and fixes a typo in a test name.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Controller as Controller\n(runner)
participant Resolver as ManagementPoliciesResolver
participant Reconciler as ManagedReconciler
participant External as ExternalSystem
Controller->>Resolver: Query allowed actions (includes "Orphan")
Resolver-->>Controller: Allowed actions (Create, Update, LateInitialize, Orphan, ...)
Controller->>Reconciler: Reconcile request (policy = Orphan)
Reconciler->>External: Perform non-Delete operations (create/update/late-init)
External-->>Reconciler: Success / Status
Reconciler-->>Controller: Conditioned status + requeue decision

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Add MustCreate management policy #873: Modifies the same ManagementAction enum and updates policy-resolution logic to add a new management action.

Suggested reviewers

• negz
• jbw976

Thanks — would you like a short changelog entry or a migration note for CRD consumers?

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding support for a new Orphan management policy, and meets the 72-character requirement.
Description check	✅ Passed	The description clearly relates to the changeset, providing context about the Orphan policy value, its purpose, testing approach, and references to related issues and documentation.
Breaking Changes	✅ Passed	This pull request introduces only additive changes to the public Go API without any breaking modifications. Two new exported constants (ManagementActionOrphan) are added to the API enum in apis/common/policies.go and apis/common/v1/policies.go, and the kubebuilder validation tag is extended to include "Orphan" as a valid value. In pkg/reconciler/managed/policies.go, the functions ShouldCreate(), ShouldUpdate(), and ShouldLateInitialize() are extended to recognize the new ManagementActionOrphan value, but their signatures remain unchanged and the behavior changes are backward-compatible. Existing code that doesn't use the new Orphan action will continue to work exactly as before. No exported functions, types, or methods are removed, renamed, or have breaking signature changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@apis/common/policies.go`:
- Line 25: The kubebuilder validation tag on the Policy enum uses a comma
between MustCreate and Orphan which prevents Orphan from being recognized; edit
the kubebuilder tag string (the line containing
"+kubebuilder:validation:Enum=Observe;Create;Update;Delete;LateInitialize;*;MustCreate,Orphan")
and replace the comma with a semicolon so it reads "...;MustCreate;Orphan" to
match the semicolon separators used elsewhere and ensure correct CRD validation.