diff --git a/content/master/guides/upgrade-to-crossplane-v2.md b/content/master/guides/upgrade-to-crossplane-v2.md index 1610a2e9..429b3a02 100644 --- a/content/master/guides/upgrade-to-crossplane-v2.md +++ b/content/master/guides/upgrade-to-crossplane-v2.md @@ -4,12 +4,12 @@ weight: 410 description: "Upgrade from Crossplane v1 to v2" --- -Crossplane v2 introduces significant improvements while maintaining backward -compatibility with most v1 configurations. This guide helps you upgrade from +Crossplane v2 introduces significant improvements while maintaining backward +compatibility with most v1 configurations. This guide helps you upgrade from Crossplane v1.x to v2. -Learn about [new features in Crossplane v2]({{}}) including -namespaced resources, the ability to compose any Kubernetes resource, and new +Learn about [new features in Crossplane v2]({{}}) including +namespaced resources, the ability to compose any Kubernetes resource, and new operational workflows. {{}} @@ -18,11 +18,11 @@ If you're running an earlier version, upgrade to v1.20 first. {{}} {{}} -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 -start using the new namespaced features right away - your existing v1 -resources continue working unchanged. See -[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) +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 +start using the new namespaced features right away - your existing v1 +resources continue working unchanged. See +[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) for migration tooling progress. {{}} @@ -45,7 +45,7 @@ Crossplane v2 removes these deprecated features: * [Default registry flag](#default-registry-flag) ### Native patch and transform composition -**Deprecated in**: v1.17 +**Deprecated in**: v1.17 **Replaced by**: [Composition functions]({{}}) If you're using `spec.mode: Resources` in your Compositions, migrate to @@ -55,14 +55,14 @@ composition functions before upgrading. Compositions: ```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 ``` ### ControllerConfig type -**Deprecated in**: v1.11 +**Deprecated in**: v1.11 **Replaced by**: [DeploymentRuntimeConfig]({{}}) 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 **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. ### Default registry flag **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: ```shell @@ -92,7 +92,7 @@ kubectl get pkg -o wide ``` 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` ## Who can upgrade @@ -112,7 +112,7 @@ If you're using any removed features, migrate away from them first. The recommended upgrade approach: 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) 4. [Upgrade providers](#4-upgrade-providers) 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 -Crossplane v2 automatically creates a default [MRAP]({{}}) that activates all managed +Crossplane v2 automatically creates a default [MRAP]({{}}) that activates all managed resources (`*`). Before installing v2 providers, you can optionally customize this for better cluster resource efficiency. @@ -159,7 +159,7 @@ Check what managed resources you use: 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: ```shell @@ -179,21 +179,21 @@ spec: # Legacy cluster-scoped resources (existing v1 resources) - buckets.s3.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 - instances.ec2.aws.m.upbound.io ``` {{}} -Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs -`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern +Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs +`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern namespaced managed resources. {{}} ### 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: ```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 namespaced. +{{}} +**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. +{{}} + To use v2 namespaced managed resources in compositions: 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 * **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. For example, existing v1-style XRDs continue working with claims: @@ -383,5 +392,5 @@ After upgrading: 3. **Try Operations**: Experiment with operational workflows 4. **Plan migration**: Consider which existing resources to migrate to v2 patterns -Read more about [what's new in v2]({{}}) and explore the +Read more about [what's new in v2]({{}}) and explore the updated [composition documentation]({{}}). diff --git a/content/v2.0/guides/upgrade-to-crossplane-v2.md b/content/v2.0/guides/upgrade-to-crossplane-v2.md index 1610a2e9..429b3a02 100644 --- a/content/v2.0/guides/upgrade-to-crossplane-v2.md +++ b/content/v2.0/guides/upgrade-to-crossplane-v2.md @@ -4,12 +4,12 @@ weight: 410 description: "Upgrade from Crossplane v1 to v2" --- -Crossplane v2 introduces significant improvements while maintaining backward -compatibility with most v1 configurations. This guide helps you upgrade from +Crossplane v2 introduces significant improvements while maintaining backward +compatibility with most v1 configurations. This guide helps you upgrade from Crossplane v1.x to v2. -Learn about [new features in Crossplane v2]({{}}) including -namespaced resources, the ability to compose any Kubernetes resource, and new +Learn about [new features in Crossplane v2]({{}}) including +namespaced resources, the ability to compose any Kubernetes resource, and new operational workflows. {{}} @@ -18,11 +18,11 @@ If you're running an earlier version, upgrade to v1.20 first. {{}} {{}} -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 -start using the new namespaced features right away - your existing v1 -resources continue working unchanged. See -[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) +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 +start using the new namespaced features right away - your existing v1 +resources continue working unchanged. See +[crossplane/crossplane#6726](https://github.com/crossplane/crossplane/issues/6726) for migration tooling progress. {{}} @@ -45,7 +45,7 @@ Crossplane v2 removes these deprecated features: * [Default registry flag](#default-registry-flag) ### Native patch and transform composition -**Deprecated in**: v1.17 +**Deprecated in**: v1.17 **Replaced by**: [Composition functions]({{}}) If you're using `spec.mode: Resources` in your Compositions, migrate to @@ -55,14 +55,14 @@ composition functions before upgrading. Compositions: ```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 ``` ### ControllerConfig type -**Deprecated in**: v1.11 +**Deprecated in**: v1.11 **Replaced by**: [DeploymentRuntimeConfig]({{}}) 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 **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. ### Default registry flag **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: ```shell @@ -92,7 +92,7 @@ kubectl get pkg -o wide ``` 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` ## Who can upgrade @@ -112,7 +112,7 @@ If you're using any removed features, migrate away from them first. The recommended upgrade approach: 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) 4. [Upgrade providers](#4-upgrade-providers) 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 -Crossplane v2 automatically creates a default [MRAP]({{}}) that activates all managed +Crossplane v2 automatically creates a default [MRAP]({{}}) that activates all managed resources (`*`). Before installing v2 providers, you can optionally customize this for better cluster resource efficiency. @@ -159,7 +159,7 @@ Check what managed resources you use: 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: ```shell @@ -179,21 +179,21 @@ spec: # Legacy cluster-scoped resources (existing v1 resources) - buckets.s3.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 - instances.ec2.aws.m.upbound.io ``` {{}} -Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs -`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern +Notice the distinction: `s3.aws.upbound.io` (legacy cluster-scoped) vs +`s3.aws.m.upbound.io` (v2 namespaced). The `.m.` indicates modern namespaced managed resources. {{}} ### 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: ```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 namespaced. +{{}} +**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. +{{}} + To use v2 namespaced managed resources in compositions: 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 * **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. For example, existing v1-style XRDs continue working with claims: @@ -383,5 +392,5 @@ After upgrading: 3. **Try Operations**: Experiment with operational workflows 4. **Plan migration**: Consider which existing resources to migrate to v2 patterns -Read more about [what's new in v2]({{}}) and explore the +Read more about [what's new in v2]({{}}) and explore the updated [composition documentation]({{}}).