WIP: Guide for updating v1 -> v2

Signed-off-by: Nic Cope <[email protected]>

Author: negz

content/master/guides/upgrade-to-crossplane-v2.md

@@ -0,0 +1,327 @@
+---
+title: Upgrade to Crossplane v2
+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 v1.x to v2.
+
+{{<hint "important">}}
+Only upgrade to Crossplane v2 from Crossplane v1.20, the final v1.x release.
+If you're running an earlier version, upgrade to v1.20 first.
+{{</hint>}}
+
+## Prerequisites
+
+Before upgrading, ensure:
+
+* You're running Crossplane v1.20
+* You're not using deprecated features (see [removed features](#removed-features))
+* All packages use fully qualified image names
+* [Helm](https://helm.sh/docs/intro/install/) version v3.2.0 or later
+
+## What changes in v2
+
+Crossplane v2 makes these major improvements:
+
+* **Namespaced resources**: Crossplane now creates both composite resources (XRs) and managed 
+  resources (MRs) in namespaces by default
+* **Compose any resource**: XRs can compose any Kubernetes resource, not just 
+  Crossplane resources
+* **Operations**: New operational workflows using function pipelines
+* **Simplified architecture**: Removes the need for claims and provider-kubernetes Objects
+
+## Removed features
+
+Crossplane v2 removes these deprecated features:
+
+* [Native patch and transform composition](#native-patch-and-transform-composition)
+* [ControllerConfig type](#controllerconfig-type)
+* [External secret stores](#external-secret-stores)
+* [Default registry flag](#default-registry-flag)
+
+### Native patch and transform composition
+**Deprecated in**: v1.17  
+**Replaced by**: [Composition functions]({{<ref "../composition/compositions">}})
+
+If you're using `spec.mode: Resources` in your Compositions, migrate to 
+composition functions before upgrading.
+
+<!-- vale Google.Headings = NO -->
+### ControllerConfig type
+<!-- vale Google.Headings = YES -->
+**Deprecated in**: v1.11  
+**Replaced by**: [DeploymentRuntimeConfig]({{<ref "../packages/providers#runtime-configuration">}})
+
+Update any ControllerConfig resources to use DeploymentRuntimeConfig instead.
+
+### External secret stores
+**Status**: alpha feature, unmaintained
+
+If you're using external secret stores, migrate to native Kubernetes secrets 
+or external secret operators before upgrading.
+
+### Default registry flag
+**Removed**: `--registry` flag for default package registry
+
+All packages must now use fully qualified image names. Check your packages 
+with:
+
+```shell
+kubectl get pkg -o wide
+```
+
+Update any packages without fully qualified names before upgrading.
+
+## Who can upgrade
+
+You can upgrade to Crossplane v2 if you meet these criteria:
+
+* ✅ Running Crossplane v1.20
+* ✅ Not using native patch and transform composition
+* ✅ Not using ControllerConfig resources
+* ✅ Not using external secret stores
+* ✅ All packages use fully qualified image names
+
+If you're using any removed features, migrate away from them first.
+
+## Upgrade approach
+
+The recommended upgrade approach:
+
+1. [Prepare for upgrade](#1-prepare-for-upgrade)
+2. [Upgrade Crossplane core](#2-upgrade-crossplane-core)  
+3. [Configure managed resource activation policies](#3-configure-managed-resource-activation-policies)
+4. [Upgrade to v2.0.0 providers](#4-upgrade-providers)
+5. [Start using v2 features](#5-start-using-v2-features)
+
+### 1. Prepare for upgrade
+
+Check for deprecated features in your cluster:
+
+```shell
+# Check for native patch and transform compositions
+kubectl get compositions -o jsonpath='{range .items[*]}{.metadata.name}: {.spec.mode}{"\n"}{end}' | grep Resources
+
+# Check for ControllerConfig resources
+kubectl get controllerconfigs
+
+# Check for packages without fully qualified names
+kubectl get pkg -o wide | grep -v '/'
+```
+
+If any of these commands return results, address them before upgrading.
+
+### 2. Upgrade Crossplane core
+
+Add the Crossplane Helm repository:
+
+```shell
+helm repo add crossplane-stable https://charts.crossplane.io/stable
+helm repo update
+```
+
+Upgrade to Crossplane v2:
+
+```shell
+helm upgrade crossplane \
+  --namespace crossplane-system \
+  crossplane-stable/crossplane \
+  --version="2.0.0"
+```
+
+Verify the upgrade:
+
+```shell
+kubectl get pods -n crossplane-system
+```
+
+### 3. Configure managed resource activation policies
+
+Crossplane v2 introduces managed resource activation policies (MRAPs) to 
+control which managed resources are active in your cluster.
+
+Create a default activation policy:
+
+```yaml
+apiVersion: apiextensions.crossplane.io/v1beta1
+kind: ManagedResourceActivationPolicy
+metadata:
+  name: default
+spec:
+  # Activate all legacy cluster-scoped MRs by default
+  activation: Default
+  selector:
+    matchLabels:
+      crossplane.io/scope: cluster
+```
+
+Apply the policy:
+
+```shell
+kubectl apply -f mrap.yaml
+```
+
+{{<hint "tip">}}
+MRAPs help reduce cluster overhead by activating only the managed resources 
+you need. See the [MRAP documentation]({{<ref "../managed-resources/managed-resource-activation-policies">}}) 
+for advanced configurations.
+{{</hint>}}
+
+### 4. Upgrade providers
+
+Upgrade your providers to versions that support both namespaced and 
+cluster-scoped managed resources:
+
+```shell
+# Check current provider versions
+kubectl get providers
+
+# Upgrade to v2.0.0 providers (example for provider-aws)
+kubectl apply -f - <<EOF
+apiVersion: pkg.crossplane.io/v1
+kind: Provider
+metadata:
+  name: provider-aws
+spec:
+  package: xpkg.crossplane.io/upbound/provider-aws:v2.0.0
+EOF
+```
+
+{{<hint "note">}}
+Provider v2.0.0 releases support both legacy cluster-scoped and new 
+namespaced managed resources. Your existing cluster-scoped MRs continue 
+working unchanged.
+{{</hint>}}
+
+### 5. Start using v2 features
+
+After upgrading, you can begin using Crossplane v2 features:
+
+#### Create namespaced XRDs
+
+Create composite resource definitions that define namespaced XRs:
+
+```yaml
+apiVersion: apiextensions.crossplane.io/v2
+kind: CompositeResourceDefinition
+metadata:
+  name: apps.example.crossplane.io
+spec:
+  scope: Namespaced  # Default in v2
+  group: example.crossplane.io
+  names:
+    kind: App
+    plural: apps
+  # schema definition...
+```
+
+#### Use namespaced managed resources
+
+Create managed resources directly in namespaces:
+
+```yaml
+apiVersion: s3.aws.m.crossplane.io/v1beta1
+kind: Bucket
+metadata:
+  name: my-bucket
+  namespace: production
+spec:
+  forProvider:
+    region: us-east-2
+```
+
+#### Try operations
+
+Explore operational workflows with the new Operations feature:
+
+```yaml
+apiVersion: ops.crossplane.io/v1alpha1
+kind: Operation
+metadata:
+  name: certificate-check
+spec:
+  mode: Pipeline
+  pipeline:
+  - step: check-certificates
+    functionRef:
+      name: crossplane-contrib-function-python
+    # function configuration...
+```
+
+## Legacy resource behavior
+
+Your existing v1 resources continue working in Crossplane v2:
+
+* **Legacy cluster-scoped XRs**: Continue working with claims support
+* **Legacy cluster-scoped MRs**: Continue working unchanged
+* **Existing Compositions**: Continue working with legacy XRs
+
+These resources use `LegacyCluster` scope internally and maintain full 
+backward compatibility.
+
+## Migration timeline
+
+There's no rush to migrate existing resources. Crossplane v2 maintains full 
+support for legacy resources:
+
+* **Immediate**: Start using v2 features for new resources
+* **Short term**: Migrate Compositions to work with v2 XRs as needed
+* **Long term**: Consider migrating existing resources to v2 patterns
+
+{{<hint "tip">}}
+Crossplane may provide automated migration tooling in future releases to 
+help transition legacy resources to v2 patterns.
+{{</hint>}}
+
+## Troubleshooting
+
+### Upgrade fails with package validation errors
+
+**Issue**: packages without fully qualified names fail validation
+
+**Solution**: update all packages to use fully qualified image names:
+
+```yaml
+apiVersion: pkg.crossplane.io/v1
+kind: Provider
+metadata:
+  name: my-provider
+spec:
+  package: registry.example.com/my-org/my-provider:v1.0.0
+```
+
+### Functions don't recognize new resource types
+
+**Issue**: composition functions can't work with new namespaced resources
+
+**Solution**: ensure you're using function versions that support both 
+cluster-scoped and namespaced resources.
+
+<!-- vale Google.Headings = NO -->
+### MRAPs not activating expected resources
+<!-- vale Google.Headings = YES -->
+
+**Issue**: expected managed resources aren't available after upgrade
+
+**Solution**: review your MRAP configuration and verify it matches your 
+resource labels:
+
+```shell
+kubectl get mraps -o yaml
+kubectl get mrds --show-labels
+```
+
+## Next steps
+
+After upgrading:
+
+1. **Explore namespaced resources**: Try creating XRs and MRs in namespaces
+2. **Build app compositions**: Use v2's ability to compose any Kubernetes resource
+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]({{<ref "../whats-new">}}) and explore the 
+updated [composition documentation]({{<ref "../composition/compositions">}}).