diff --git a/cluster/UPGRADE.md b/cluster/UPGRADE.md index 58091a431d..3ac08ea8a2 100644 --- a/cluster/UPGRADE.md +++ b/cluster/UPGRADE.md @@ -1,3 +1,166 @@ +# Upgrade from v0.32.x to v0.33.x + +There are deprecated resources in `v0.33.0` that were removed. +`SNS` esources were used to be represented in `notification.aws.crossplane.io` +but now they are moved to `sns.aws.crossplane.io`, their versions got upgraded +to `v1beta1` and `SNS` prefix is dropped from their name. + +Thanks to package manager, old CRDs are not deleted once you upgrade to the new +version; only their controllers are stopped, which gives users time to create +corresponding new types. + +The first step is to upgrade to the new version: +```bash +# Find the name of your Provider object. +kubectl get provider.pkg +# Patch it with the new version. Make sure you use the latest patch release of +# v0.33.x +kubectl patch provider.pkg -p '{"spec":{"package": "crossplanecontrib/provider-aws:v0.33.0"}}' --type=merge +``` + +At this point, there is no controller reconciling your existing `notification` custom resources. +We will create new CRs that correspond to those old `notification` CRs but have new type, +and then clean up the old CRs. + +## Create using new CRDs + +Create new custom resources (CR) with the new metadata: + +```bash +# SNSTopic +kubectl get SNSTopic.notification.aws.crossplane.io -ojson \ + | jq 'del(.items[].metadata.namespace,.items[].metadata.resourceVersion,.items[].metadata.uid,.items[].metadata.generation) | .items[].metadata.creationTimestamp=null' \ + | sed 's|notification.aws.crossplane.io/v1alpha1|sns.aws.crossplane.io/v1beta1|g' \ + | sed 's|SNSTopic|Topic|g' \ + | kubectl apply -f - + +# SNSSubscription +kubectl get SNSSubscription.notification.aws.crossplane.io -ojson \ + | jq 'del(.items[].metadata.namespace,.items[].metadata.resourceVersion,.items[].metadata.uid,.items[].metadata.generation) | .items[].metadata.creationTimestamp=null' \ + | sed 's|notification.aws.crossplane.io/v1alpha1|sns.aws.crossplane.io/v1beta1|g' \ + | sed 's|SNSSubscription|Subscription|g' \ + | kubectl apply -f - +``` + +Check whether we have created a counterpart for all CR instances. +```bash +# The number of old CRs in notification group. +kubectl get aws -o name | grep 'notification.aws.crossplane.io' | wc -l +# The number of new CRs in sns group. This number should be equal to the number +# of old CRs from notification group. +kubectl get aws -o name | grep 'sns.aws.crossplane.io' | wc -l +``` + +## Update Composition References + +If you didn't use `Composition` to deploy these resources, you can skip this step and +continue with the clean up. + +We need to edit each and every composite resource (XR) that references to the old ojects +to make them point to the new CRs we just created. In addition, we'll also need to +update `Composition` objects so that future creations use the new CRDs. + +Since Crossplane is actively reconciling the composite resource and `Composition`, we +need to scale it down so that it doesn't create duplicate CRs while we're doing the +changes. + +```bash +# Make sure to check the namespace. +kubectl -n crossplane-system scale deployment crossplane --replicas=0 +``` + +We will first edit the `Composition` objects to use the new CRD `apiVersion` and `kind`s. +Find all `Composition`s to see which of them uses `SNS` resources: +```bash +kubectl get composition +``` + +In each element of the `spec.resources` array, make sure all `SNS` resources have the new +`apiVersion` and `kind`. + +```yaml +apiVersion: apiextensions.crossplane.io/v1 +kind: Composition +metadata: + name: xnotification.aws.notification.example.org +spec: + ... + resources: + - name: subscription + base: + apiVersion: notification.aws.crossplane.io/v1alpha1 # <--- change this to the new group, sns.aws.crossplane.io/v1beta1 + kind: SNSSubscription # <--- change this to the new kind, i.e. "Subscription" in this case. + spec: + ... +``` + + +You will now need to edit composite resources that has composed resources with the old +CRDs. Get the list of all composite resources: +```bash +kubectl get composite +``` + +```yaml +# Assuming the composite type is Xnotification +kubectl edit Xnotification resource-wfmfp +``` + +The changes you need to make are as following: +```yaml +spec: + ... + resourceRefs: + - apiVersion: notification.aws.crossplane.io/v1alpha1 # <--- change this to the new group, sns.aws.crossplane.io/v1beta1 + kind: SNSSubscription # <--- change type to the new name, i.e. Subscription in this case. + name: platform-ref-aws-cluster-mwx8t-5j9hv # <--- make sure there is a resource with this name whose kind + # Make the changes described above for every entry in this array. + writeConnectionSecretToRef: + ... +``` + +At this point, everything looks like they were created with these `apiVersion` and `kind` +in the first place. Before scaling Crossplane up again, let's check how many `notification` resources +exist in the cluster at this point so that we can be sure no duplicate is created +by composition controller: +```bash +kubectl get aws -o name | grep 'notification.aws.crossplane.io' | wc -l +``` + +We can bring back Crossplane: +```bash +kubectl -n crossplane-system scale deployment crossplane --replicas=1 +``` + +After it's up and running check how many resources are there now and compare with the initial number: +```bash +kubectl get aws -o name | grep 'notification.aws.crossplane.io' | wc -l +``` + +All good if the numbers match! + +## Clean up the old CRs + +Now that the new ones took place of the old ones, we can delete the old ones: +```bash +# Since no controller is reconciling them, we need to remove the finalizer to +# unblock deletion. +kubectl get aws -o name \ + | grep 'notification.aws.crossplane.io' \ + | xargs -I {} kubectl patch {} -p '{"metadata":{"finalizers": []}}' --type=merge +# Delete all resources in notification group +kubectl get aws -o name \ + | grep 'notification.aws.crossplane.io' \ + | xargs kubectl delete +``` + +You can check whether there is any remaining CRs from the old types: +```bash +kubectl get aws -o name | grep 'notification.aws.crossplane.io' +``` + +Done! You can check all resources by running `kubectl get managed`. + # Upgrade from v0.21.x to v0.22.x There are number of resources in `v0.22.0` that were upgraded to `v1beta1`. Most