crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add warning to v2 upgrade guide to not migrate live compositions 

Signed-off-by: Jared Watts <jbw976@gmail.com>
This commit is contained in:
Jared Watts 2025-09-03 14:16:45 -07:00
parent b63d34e6a0
commit 0248bb39c6
No known key found for this signature in database
GPG Key ID: 0467EEAE3B6EC0D2
2 changed files with 68 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
content/master/guides/upgrade-to-crossplane-v2.md
View File

@ -4,12 +4,12 @@ weight: 410
description: "Upgrade from Crossplane v1 to v2" description: "Upgrade from Crossplane v1 to v2"
--- ---
Crossplane v2 introduces significant improvements while maintaining backward Crossplane v2 introduces significant improvements while maintaining backward
compatibility with most v1 configurations. This guide helps you upgrade from compatibility with most v1 configurations. This guide helps you upgrade from
Crossplane v1.x to v2. Crossplane v1.x to v2.
Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including
namespaced resources, the ability to compose any Kubernetes resource, and new namespaced resources, the ability to compose any Kubernetes resource, and new
operational workflows. operational workflows.
{{<hint "important">}} {{<hint "important">}}
@ -18,11 +18,11 @@ If you're running an earlier version, upgrade to v1.20 first.
{{</hint>}} {{</hint>}}
{{<hint "note">}} {{<hint "note">}}
There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and
MRs to v2 namespaced style. You can upgrade to Crossplane v2 and MRs to v2 namespaced style. You can upgrade to Crossplane v2 and
start using the new namespaced features right away - your existing v1 start using the new namespaced features right away - your existing v1
resources continue working unchanged. See resources continue working unchanged. See
[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) [crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726)
for migration tooling progress. for migration tooling progress.
{{</hint>}} {{</hint>}}
@ -45,7 +45,7 @@ Crossplane v2 removes these deprecated features:
* [Default registry flag](#default-registry-flag) * [Default registry flag](#default-registry-flag)
### Native patch and transform composition ### Native patch and transform composition
**Deprecated in**: v1.17 **Deprecated in**: v1.17
**Replaced by**: [Composition functions]({{<ref "../composition/compositions">}}) **Replaced by**: [Composition functions]({{<ref "../composition/compositions">}})
If you're using `spec.mode: Resources` in your Compositions, migrate to If you're using `spec.mode: Resources` in your Compositions, migrate to
@ -55,14 +55,14 @@ composition functions before upgrading.
Compositions: Compositions:
```shell ```shell
# Convert patch and transform to function pipelines # Convert patch and transform to function pipelines
crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml
``` ```
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
### ControllerConfig type ### ControllerConfig type
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
**Deprecated in**: v1.11 **Deprecated in**: v1.11
**Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}}) **Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}})
Update any ControllerConfig resources to use DeploymentRuntimeConfig instead. Update any ControllerConfig resources to use DeploymentRuntimeConfig instead.
@ -78,13 +78,13 @@ crossplane beta convert deployment-runtime controller-config.yaml -o deployment-
### External secret stores ### External secret stores
**Status**: alpha feature, unmaintained **Status**: alpha feature, unmaintained
If you're using external secret stores, migrate to native Kubernetes secrets If you're using external secret stores, migrate to native Kubernetes secrets
or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading. or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading.
### Default registry flag ### Default registry flag
**Removed**: `--registry` flag for default package registry **Removed**: `--registry` flag for default package registry
All packages must now use fully qualified names including the registry All packages must now use fully qualified names including the registry
host name. Check your packages with: host name. Check your packages with:
```shell ```shell
@ -92,7 +92,7 @@ kubectl get pkg -o wide
``` ```
Update any packages without registry host names before upgrading. For example: Update any packages without registry host names before upgrading. For example:
- ❌ `crossplane-contrib/provider-aws-s3:v1.23.0` - ❌ `crossplane-contrib/provider-aws-s3:v1.23.0`
- ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0` - ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0`
## Who can upgrade ## Who can upgrade
@ -112,7 +112,7 @@ If you're using any removed features, migrate away from them first.
The recommended upgrade approach: The recommended upgrade approach:
1. [Prepare for upgrade](#1-prepare-for-upgrade) 1. [Prepare for upgrade](#1-prepare-for-upgrade)
2. [Upgrade Crossplane core](#2-upgrade-crossplane-core) 2. [Upgrade Crossplane core](#2-upgrade-crossplane-core)
3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies) 3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies)
4. [Upgrade providers](#4-upgrade-providers) 4. [Upgrade providers](#4-upgrade-providers)
5. [Start using v2 features](#5-start-using-v2-features) 5. [Start using v2 features](#5-start-using-v2-features)
@ -148,7 +148,7 @@ kubectl get pods -n crossplane-system
### 3. Configure managed resource activation policies ### 3. Configure managed resource activation policies
Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed
resources (`*`). Before installing v2 providers, you can optionally customize resources (`*`). Before installing v2 providers, you can optionally customize
this for better cluster resource efficiency. this for better cluster resource efficiency.
@ -159,7 +159,7 @@ Check what managed resources you use:
kubectl get managed kubectl get managed
``` ```
Optionally, replace the default MRAP with a targeted one that activates only Optionally, replace the default MRAP with a targeted one that activates only
the resources you need: the resources you need:
```shell ```shell
@ -179,21 +179,21 @@ spec:
# Legacy cluster-scoped resources (existing v1 resources) # Legacy cluster-scoped resources (existing v1 resources)
- buckets.s3.aws.upbound.io - buckets.s3.aws.upbound.io
- instances.ec2.aws.upbound.io - instances.ec2.aws.upbound.io
# Modern namespaced resources (new v2 resources) # Modern namespaced resources (new v2 resources)
- buckets.s3.aws.m.upbound.io - buckets.s3.aws.m.upbound.io
- instances.ec2.aws.m.upbound.io - instances.ec2.aws.m.upbound.io
``` ```
{{<hint "tip">}} {{<hint "tip">}}
Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs
`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern `s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern
namespaced managed resources. namespaced managed resources.
{{</hint>}} {{</hint>}}
### 4. Upgrade providers ### 4. Upgrade providers
Upgrade your providers to versions that support both namespaced and Upgrade your providers to versions that support both namespaced and
cluster-scoped managed resources: cluster-scoped managed resources:
```shell ```shell
@ -232,6 +232,15 @@ Existing Compositions work with Crossplane v2 with minimal changes. v2 managed
resources are schematically identical to v1 managed resources - they're just resources are schematically identical to v1 managed resources - they're just
namespaced. namespaced.
{{<hint "important">}}
**Don't update existing compositions that are actively used by composite
resources in your control plane.**
Updating a live composition that's in use by existing XRs could disrupt or
replace your resources. Use the below migration approach only when creating new
compositions for new resources.
{{</hint>}}
To use v2 namespaced managed resources in compositions: To use v2 namespaced managed resources in compositions:
1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io` 1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io`
@ -337,7 +346,7 @@ Your existing v1 resources continue working in Crossplane v2:
* **Legacy cluster-scoped MRs**: Continue working unchanged * **Legacy cluster-scoped MRs**: Continue working unchanged
* **Existing Compositions**: Continue working with legacy XRs * **Existing Compositions**: Continue working with legacy XRs
These resources use `LegacyCluster` scope internally and maintain full These resources use `LegacyCluster` scope internally and maintain full
backward compatibility. backward compatibility.
For example, existing v1-style XRDs continue working with claims: For example, existing v1-style XRDs continue working with claims:
@ -383,5 +392,5 @@ After upgrading:
3. **Try Operations**: Experiment with operational workflows 3. **Try Operations**: Experiment with operational workflows
4. **Plan migration**: Consider which existing resources to migrate to v2 patterns 4. **Plan migration**: Consider which existing resources to migrate to v2 patterns
Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the
updated [composition documentation]({{<ref "../composition/compositions">}}). updated [composition documentation]({{<ref "../composition/compositions">}}).

59
content/v2.0/guides/upgrade-to-crossplane-v2.md
View File

@ -4,12 +4,12 @@ weight: 410
description: "Upgrade from Crossplane v1 to v2" description: "Upgrade from Crossplane v1 to v2"
--- ---
Crossplane v2 introduces significant improvements while maintaining backward Crossplane v2 introduces significant improvements while maintaining backward
compatibility with most v1 configurations. This guide helps you upgrade from compatibility with most v1 configurations. This guide helps you upgrade from
Crossplane v1.x to v2. Crossplane v1.x to v2.
Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including Learn about [new features in Crossplane v2]({{<ref "../whats-new">}}) including
namespaced resources, the ability to compose any Kubernetes resource, and new namespaced resources, the ability to compose any Kubernetes resource, and new
operational workflows. operational workflows.
{{<hint "important">}} {{<hint "important">}}
@ -18,11 +18,11 @@ If you're running an earlier version, upgrade to v1.20 first.
{{</hint>}} {{</hint>}}
{{<hint "note">}} {{<hint "note">}}
There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and There's no automated tooling yet to migrate existing v1 cluster-scoped XRs and
MRs to v2 namespaced style. You can upgrade to Crossplane v2 and MRs to v2 namespaced style. You can upgrade to Crossplane v2 and
start using the new namespaced features right away - your existing v1 start using the new namespaced features right away - your existing v1
resources continue working unchanged. See resources continue working unchanged. See
[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) [crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726)
for migration tooling progress. for migration tooling progress.
{{</hint>}} {{</hint>}}
@ -45,7 +45,7 @@ Crossplane v2 removes these deprecated features:
* [Default registry flag](#default-registry-flag) * [Default registry flag](#default-registry-flag)
### Native patch and transform composition ### Native patch and transform composition
**Deprecated in**: v1.17 **Deprecated in**: v1.17
**Replaced by**: [Composition functions]({{<ref "../composition/compositions">}}) **Replaced by**: [Composition functions]({{<ref "../composition/compositions">}})
If you're using `spec.mode: Resources` in your Compositions, migrate to If you're using `spec.mode: Resources` in your Compositions, migrate to
@ -55,14 +55,14 @@ composition functions before upgrading.
Compositions: Compositions:
```shell ```shell
# Convert patch and transform to function pipelines # Convert patch and transform to function pipelines
crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml crossplane beta convert pipeline-composition old-composition.yaml -o new-composition.yaml
``` ```
<!-- vale Google.Headings = NO --> <!-- vale Google.Headings = NO -->
### ControllerConfig type ### ControllerConfig type
<!-- vale Google.Headings = YES --> <!-- vale Google.Headings = YES -->
**Deprecated in**: v1.11 **Deprecated in**: v1.11
**Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}}) **Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}})
Update any ControllerConfig resources to use DeploymentRuntimeConfig instead. Update any ControllerConfig resources to use DeploymentRuntimeConfig instead.
@ -78,13 +78,13 @@ crossplane beta convert deployment-runtime controller-config.yaml -o deployment-
### External secret stores ### External secret stores
**Status**: alpha feature, unmaintained **Status**: alpha feature, unmaintained
If you're using external secret stores, migrate to native Kubernetes secrets If you're using external secret stores, migrate to native Kubernetes secrets
or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading. or [External Secrets Operator](https://external-secrets.io/latest/) before upgrading.
### Default registry flag ### Default registry flag
**Removed**: `--registry` flag for default package registry **Removed**: `--registry` flag for default package registry
All packages must now use fully qualified names including the registry All packages must now use fully qualified names including the registry
host name. Check your packages with: host name. Check your packages with:
```shell ```shell
@ -92,7 +92,7 @@ kubectl get pkg -o wide
``` ```
Update any packages without registry host names before upgrading. For example: Update any packages without registry host names before upgrading. For example:
- ❌ `crossplane-contrib/provider-aws-s3:v1.23.0` - ❌ `crossplane-contrib/provider-aws-s3:v1.23.0`
- ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0` - ✅ `xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.23.0`
## Who can upgrade ## Who can upgrade
@ -112,7 +112,7 @@ If you're using any removed features, migrate away from them first.
The recommended upgrade approach: The recommended upgrade approach:
1. [Prepare for upgrade](#1-prepare-for-upgrade) 1. [Prepare for upgrade](#1-prepare-for-upgrade)
2. [Upgrade Crossplane core](#2-upgrade-crossplane-core) 2. [Upgrade Crossplane core](#2-upgrade-crossplane-core)
3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies) 3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies)
4. [Upgrade providers](#4-upgrade-providers) 4. [Upgrade providers](#4-upgrade-providers)
5. [Start using v2 features](#5-start-using-v2-features) 5. [Start using v2 features](#5-start-using-v2-features)
@ -148,7 +148,7 @@ kubectl get pods -n crossplane-system
### 3. Configure managed resource activation policies ### 3. Configure managed resource activation policies
Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed Crossplane v2 automatically creates a default [MRAP]({{<ref "../managed-resources/managed-resource-activation-policies">}}) that activates all managed
resources (`*`). Before installing v2 providers, you can optionally customize resources (`*`). Before installing v2 providers, you can optionally customize
this for better cluster resource efficiency. this for better cluster resource efficiency.
@ -159,7 +159,7 @@ Check what managed resources you use:
kubectl get managed kubectl get managed
``` ```
Optionally, replace the default MRAP with a targeted one that activates only Optionally, replace the default MRAP with a targeted one that activates only
the resources you need: the resources you need:
```shell ```shell
@ -179,21 +179,21 @@ spec:
# Legacy cluster-scoped resources (existing v1 resources) # Legacy cluster-scoped resources (existing v1 resources)
- buckets.s3.aws.upbound.io - buckets.s3.aws.upbound.io
- instances.ec2.aws.upbound.io - instances.ec2.aws.upbound.io
# Modern namespaced resources (new v2 resources) # Modern namespaced resources (new v2 resources)
- buckets.s3.aws.m.upbound.io - buckets.s3.aws.m.upbound.io
- instances.ec2.aws.m.upbound.io - instances.ec2.aws.m.upbound.io
``` ```
{{<hint "tip">}} {{<hint "tip">}}
Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs
`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern `s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern
namespaced managed resources. namespaced managed resources.
{{</hint>}} {{</hint>}}
### 4. Upgrade providers ### 4. Upgrade providers
Upgrade your providers to versions that support both namespaced and Upgrade your providers to versions that support both namespaced and
cluster-scoped managed resources: cluster-scoped managed resources:
```shell ```shell
@ -232,6 +232,15 @@ Existing Compositions work with Crossplane v2 with minimal changes. v2 managed
resources are schematically identical to v1 managed resources - they're just resources are schematically identical to v1 managed resources - they're just
namespaced. namespaced.
{{<hint "important">}}
**Don't update existing compositions that are actively used by composite
resources in your control plane.**
Updating a live composition that's in use by existing XRs could disrupt or
replace your resources. Use the below migration approach only when creating new
compositions for new resources.
{{</hint>}}
To use v2 namespaced managed resources in compositions: To use v2 namespaced managed resources in compositions:
1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io` 1. **Update the API group** from `.crossplane.io` to `.m.crossplane.io`
@ -337,7 +346,7 @@ Your existing v1 resources continue working in Crossplane v2:
* **Legacy cluster-scoped MRs**: Continue working unchanged * **Legacy cluster-scoped MRs**: Continue working unchanged
* **Existing Compositions**: Continue working with legacy XRs * **Existing Compositions**: Continue working with legacy XRs
These resources use `LegacyCluster` scope internally and maintain full These resources use `LegacyCluster` scope internally and maintain full
backward compatibility. backward compatibility.
For example, existing v1-style XRDs continue working with claims: For example, existing v1-style XRDs continue working with claims:
@ -383,5 +392,5 @@ After upgrading:
3. **Try Operations**: Experiment with operational workflows 3. **Try Operations**: Experiment with operational workflows
4. **Plan migration**: Consider which existing resources to migrate to v2 patterns 4. **Plan migration**: Consider which existing resources to migrate to v2 patterns
Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the Read more about [what's new in v2]({{<ref "../whats-new">}}) and explore the
updated [composition documentation]({{<ref "../composition/compositions">}}). updated [composition documentation]({{<ref "../composition/compositions">}}).