Crossplane v2 Upgrade: `ControllerConfig` and Native Patch-and-Transform Remo... — when and how should I migrate?
Decide whether a Crossplane platform can upgrade to v2 now or must first migrate off removed features such as `ControllerConfig`, external secret stores, native patch-and-transform composition, and related deprecated packaging behavior.
Blockers
- Official upgrade guidance says you can upgrade to v2 if you are already on Crossplane v1.20.
- ControllerConfig is removed in the v2 line.
- Native patch-and-transform composition is removed in the v2 line.
- External secret stores are removed in the v2 line.
- Composite resource connection details support is removed in the v2 line.
- The default package registry behavior is removed in the v2 line.
Who this is for
- enterprise
- low-ops
Candidates
Upgrade to Crossplane v2 now after prerequisite migrations
As of 2026-03-27, Crossplane's official upgrade guide says you can upgrade to v2 if you are already on Crossplane v1.20, are not using native patch-and-transform composition, are not using `ControllerConfig`, are not using external secret stores, and all packages use fully qualified image names. Crossplane's v2 docs also state that existing v1 resources continue working unchanged and that most users can upgrade from v1.x to v2 without breaking changes once those removals are addressed. The removed features are not soft warnings in v2: native patch-and-transform composition, `ControllerConfig`, external secret stores, composite resource connection details support, and the default package registry behavior are all removed in the v2 line. This path is the right choice only after those blockers are eliminated.
When to choose
Use this when your control plane is already standardized on v1.20 and your audit confirms none of the removed features are still in active manifests. The decisive factor is that Crossplane v2 remains backward compatible for most v1 installations only if those deprecated and alpha features are already out of use.
Tradeoffs
You get onto the current v2 model and can start using namespaced v2 features while keeping existing v1-style resources running, but you must accept the v2 removals immediately and update package references to fully qualified registry names.
Cautions
Do not assume `ControllerConfig`, `spec.mode: Resources`, or `spec.publishConnectionDetailsTo` will continue to work after the core upgrade. If you relied on composite resource connection details support, Crossplane v2 removes that native behavior and you must rebuild it using composition patterns described in the docs.
Stay on Crossplane v1.20 while you migrate removed features first
As of 2026-03-27, Crossplane's official guidance is explicit that teams using removed features must migrate away from them before upgrading to v2. The upgrade guide provides conversion help from the v1.20 CLI for both native patch-and-transform compositions and `ControllerConfig` resources, and it recommends migrating external secret store users to native Kubernetes Secrets or External Secrets Operator before moving to v2. The same guide also states there is no automated tooling yet to migrate existing v1 cluster-scoped XRs and MRs to the new v2 namespaced style, which makes a staged migration safer for installations with many legacy resources. This option is the safer default when you still have deprecated constructs in production manifests.
When to choose
Use this when your audit still finds `spec.mode: Resources`, `ControllerConfig`, external secret store usage, or non-fully-qualified package image references. The decisive factor is that these are blocker-level incompatibilities for the v2 upgrade path, not optional cleanup items.
Tradeoffs
This reduces upgrade risk and gives you time to convert manifests with official tooling, but it delays access to the v2 feature set and extends the period you operate on the older control-plane model.
Cautions
Treat this as a migration hold, not a long-term steady state. Crossplane documents the v2 removals clearly, so deferring the upgrade without scheduling manifest conversions just postpones unavoidable work.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Crossplane v2 Upgrade: `ControllerConfig` and Native Patch-and-Transform Remo... — when and how should I migrate?"