Selected work  /  Deloitte  ·  2024–2025

Fifty-four Terraform modules to Crossplane, in place

A whole estate — 54 modules, roughly 190 distinct AWS resource types — moved off Terraform and onto a Kubernetes-native control plane, without recreating the infrastructure underneath it. Nothing was rebuilt. That constraint is what made it a year of work rather than a quarter.

Scope
54 Terraform modules
Surface
~190 AWS resource types
Method
In-place adoption
Recreated
Nothing

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.

Ownership handover per resource Five stages. Terraform owns the resource through stages one to three. Crossplane observes from stage two, takes full management at stage four, and Terraform's ownership is removed at stage five via terraform state rm. The two systems overlap only while Crossplane is read-only. who owns the resource Terraform — writes Crossplane — observes only ······· writes 1 · Baseline clean plan 2 · Adopt crossplane.io/ external-name 3 · Prove Observe only, no diff, N cycles 4 · Hand over management Policies: ["*"] 5 · Release terraform state rm the only risky window Both systems present. Crossplane cannot write, so the worst case is a stale read.
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

  1. Baseline. A clean terraform plan first. Migrating a resource that already has pending drift means spending the next day arguing about whether Crossplane caused it.
  2. Adopt. Write the managed resource with crossplane.io/external-name set 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."
  3. Prove. managementPolicies: ["Observe"]. Let it reconcile, then compare status.atProvider against 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.
  4. Hand over. Widen to ["*"]. Crossplane owns writes from here.
  5. Release. terraform state rm, then delete the resource block. In that order. Reversing them puts a destroy in 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.