Crossplane migration post-mortem: Great concept, rough edges cost us two sprints.

We were early adopters of Crossplane for our internal platform, drawn in by the powerful concept of a universal control plane. The idea of managing everything—cloud resources, databases, even SaaS configurations—with Kubernetes-style declarative YAML was incredibly compelling. We ran a successful pilot, but our recent migration from a pure-Terraform-module-based setup for our GCP foundation to a full Crossplane Composite Resource (XR) model hit some very real snags. I'm documenting this not to discourage its use, but to give a realistic account of where the friction points were for a team like ours.

Our goal was to migrate a core set of about 15 foundational resources—things like GCP projects, service accounts, VPCs, and subnetworks—from our maintained Terraform modules over to a Crossplane `Composition`. We estimated one sprint. It took two, plus some spillover. Here’s a breakdown of where the time went:

* **State Migration & Adoption:** This was the single biggest time sink. The Terraform state file was our source of truth. While Crossplane can adopt existing resources, the process is manual and meticulous for each resource type. We had to write one-off scripts to map Terraform outputs to the specific `external-name` annotation pattern Crossplane expects. Any mistake meant Crossplane would try to re-create the resource, a risk we couldn't take for production projects.
* **Composition Complexity:** Designing the `Composition` templates to be as flexible and reusable as our Terraform modules required deep diving into Patches and Transforms. The logic that was a variable in Terraform (e.g., `map(any)`) often became a PatchSet with several steps. Getting the patch ordering right for dependencies between fields was a lot of trial and error.
* **Debugging & Observability:** When a `ManagedResource` (the individual Crossplane resources) gets "stuck" in an unhealthy state, the error messages are often deeply nested Kubernetes status conditions. It took us a while to build an effective mental model (and later, some internal dashboards) to trace from the high-level XR down to the specific provider error. Terraform's plan/apply output, while verbose, is linear and often easier to parse initially.
* **Documentation & Community Gap:** For Terraform, you can almost always find a ready-made example for any GCP resource. With Crossplane, you're often stitching together the generic Crossplane Composition docs with the specific GCP provider's API reference. The patterns are there, but the library of real-world, complex examples is still growing.

So, was it worth it? For us, **yes, but with caveats.** The win is now fully realized: platform teams define the XR, and application teams can safely self-serve a configured GCP project with proper guardrails via a simple Kubernetes manifest. The integration with our existing Kubernetes RBAC and GitOps workflow is seamless. However, the migration cost was significant.

My takeaways for anyone considering a similar move:

* **Don't migrate, adopt.** If starting greenfield, Crossplane is fantastic. For brownfield, consider a phased adoption where new resources use Crossplane and old ones are migrated only when they need major changes.
* **Invest in internal tooling early.** Build those debugging dashboards and adoption scripts *before* the full migration. It will pay off immediately.
* **Treat Compositions like product code.** They require the same level of design review, testing, and documentation as any critical internal library.

The "rough edges" were primarily in the ecosystem and tooling maturity, not the core concept. It's a powerful paradigm shift, but you need to budget for the learning curve and the manual transition work.

Has anyone else gone through a similar Terraform-to-Crossplane migration? How did you tackle the state import challenge? I'd love to compare notes.

~jenny