Why move at all
Terraform was doing its job. The reason to move was not that it was broken; it was that the rest of the platform had become Kubernetes-native and this estate had not. Two systems of record for infrastructure means two review paths, two drift stories, and a permanent question about which one is authoritative when they disagree.
The second reason is the drift story itself. Terraform notices drift when somebody runs plan.
A Crossplane managed resource notices it on every reconcile and corrects it, and the correction is an
event you can point at. In an environment where "prove this has been enforced continuously" is a real
question, that difference is worth a migration on its own.
The constraint that shapes everything
Two tools that both believe they own a resource is the failure mode to design against. Terraform sees a change Crossplane made and reverts it; Crossplane sees the revert and re-applies. Nothing crashes, and the resource oscillates until somebody notices the CloudTrail bill.
So the work is not really about Crossplane. It is about handing over ownership of each resource exactly once, in a defined order, with a period in which you can prove the new owner would do nothing before you allow it to do anything. Multiply that by 54 modules and the interesting engineering is all in the procedure.
managementPolicies is what makes this safe. A managed resource set to ["Observe"]
reconciles, populates status.atProvider, and writes nothing — so you can compare what
Crossplane would do against what exists, for as long as you like, before granting it the pen.
The procedure, per resource
-
Baseline. A clean
terraform planfirst. Migrating a resource that already has pending drift means spending the next day arguing about whether Crossplane caused it. -
Adopt. Write the managed resource with
crossplane.io/external-nameset to the existing resource's real identifier. That annotation is the whole trick: it is how a provider knows "this object refers to something that already exists" rather than "create one." -
Prove.
managementPolicies: ["Observe"]. Let it reconcile, then comparestatus.atProvideragainst the Terraform state and against reality. Anything that comes back different is either a real difference or a provider default nobody ever wrote down — and finding that out while the resource is read-only costs nothing. -
Hand over. Widen to
["*"]. Crossplane owns writes from here. -
Release.
terraform state rm, then delete the resource block. In that order. Reversing them puts adestroyin the plan, and a destroy here is an incident.
# Stage 3 — adopted, watching, deliberately unable to touch anything. apiVersion: s3.aws.upbound.io/v1beta1 kind: Bucket metadata: name: artifact-store annotations: # the bucket that already exists — do not create a new one crossplane.io/external-name: platform-artifact-store spec: managementPolicies: ["Observe"] # → ["*"] after a clean diff deletionPolicy: Orphan # until the dust settles
What bit
Defaults nobody wrote down
The commonest surprise in stage 3 is a field Terraform left implicit that the managed resource reports explicitly, or the reverse. Neither tool is wrong; the resource simply has a value nobody ever declared. Across ~190 resource types there are a lot of those, and each one is a small decision about what the desired state actually is. Making those decisions during a read-only window rather than during a write is the difference between a migration and an outage.
Ordering across 54 modules
Modules do not migrate independently when one references another. Anything still referenced by a Terraform-owned resource has to keep a stable identifier through the handover, which in practice means migrating from the leaves inward and resisting every urge to batch.
Deletion policy is the sharp edge
A Crossplane managed resource deletes the real thing when the Kubernetes object is deleted, and a
migration involves creating and reshuffling a great many Kubernetes objects.
deletionPolicy: Orphan on anything stateful until the estate is stable is cheap insurance,
and turning it back is a one-line diff.
Outcome
- 54 Terraform modules, roughly 190 distinct AWS resource types, moved onto a Kubernetes-native Crossplane control plane.
- Done in place. Nothing recreated, and no window in which the estate was unowned.
- Drift detection moved from "when somebody runs plan" to "every reconcile."
- One system of record for infrastructure instead of two.
Would I always do this?
No, and I would say so in an interview. Crossplane earns its keep when infrastructure needs to be self-service, continuously reconciled, or composed into a platform API other teams consume. If a team is happy with Terraform, has one system of record, and nobody is asking for self-service, the migration is cost without benefit. Here the rest of the platform was already Kubernetes-native, and the estate was the last thing holding a second system of record open.
Client details are deliberately absent. Happy to go deeper on the mechanics in conversation.