Adding crossplane.io/external-name to a composition for existing resources — is it safe, and how to re-adopt existing external resources

Issue

• Planning to add an explicit crossplane.io/external-name annotation to a composition for resources that are already deployed

• Concern: will this be a safe no-op, or could it trigger re-creation, adoption conflicts, or duplicate resources?

• Context: managementPolicies was parameterized to exclude Delete (so the external resource survives when a claim is removed)

• After deleting a claim, the managed resource left the cluster but the external resource remained (intended)

• Re-applying the same claim failed with "Already Exists" — with no crossplane.io/external-name, Crossplane tried to create a new resource instead of adopting the existing one

Environment

• Crossplane / UXP v1.18, Self-Hosted Spaces

• provider-github (GitHub Repository) — behavior applies to any provider/resource type

• managementPolicies configured to exclude Delete

Resolution

• Declaring crossplane.io/external-name is the correct, common way to adopt (or re-adopt) an existing external resource

• Safe no-op for existing MRs ONLY IF the declared value equals the value already on the MR (the provider populates external-name after create)

• Match → Crossplane sees no diff → no re-creation, no adoption conflict, no duplicates

• Mismatch → Crossplane looks for the resource under the wrong name and tries to create it → "Already Exists"

• With Delete excluded from managementPolicies, the external resource survives claim deletion; re-applying requires external-name to re-adopt it

• Verify before rollout: the external-name you declare matches what the provider already set (often derived from the same expression as spec.forProvider.name)

Reusable composition design (avoid tying a composition to one instance)

• Do not hardcode a single external-name in a shared composition — that ties the blueprint to one live resource

• Make external-name optional in the XR spec (e.g. a per-resource list); the composition adds it to the MR annotation only when present

• Keeps the composition a reusable blueprint while still supporting adoption

Recommended tooling

• function-external-name-backup-restore is purpose-built to store/restore external names for this scenario — a cleaner long-term alternative to declaring them inline

• Crossplane guide: Import existing resources

Cause

• Crossplane reconstructs external state on every observation; crossplane.io/external-name is the key it uses to call the cloud API and locate the existing resource

• If external-name is missing or does not match the real resource, Crossplane assumes the resource does not exist and attempts to create it → "Already Exists" when it actually exists