Update extension upgrade tutorial doc

trgeiger · trgeiger · commit f70dafd7f7af · 2024-11-15T13:42:04.000-06:00
With the addition of the CRD Upgrade Safety preflight check, our
existing example of upgrading argocd from 0.5.0 to 0.6.0 no longer
serves as a good example. This commit changes the example to use an
update from 0.2.0 to 0.2.1 which no longer fails the CRD Upgrade check,
and also doesn't violate our restriction on automatic upgrades between
minor versions with a major version of zero.

Signed-off-by: Tayler Geiger &lt;tayler@redhat.com&gt;
diff --git a/docs/getting-started/olmv1_getting_started.md b/docs/getting-started/olmv1_getting_started.md
@@ -73,12 +73,11 @@ kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-c
 To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
 there must be CRD compatibility between the versions being upgraded, and the target version must be
 compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md),
-compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md),
-and on the extension upgrade process [here](../tutorials/upgrade-extension.md).
+and more information on the extension upgrade process can be found [here](../tutorials/upgrade-extension.md).
 
 ```bash
 # Update to v0.11.0
-kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
+kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.2.1"}}}}'
 ```
 
 For information on the downgrade process, see [here](../tutorials/downgrade-extension.md).
diff --git a/docs/tutorials/upgrade-extension.md b/docs/tutorials/upgrade-extension.md
@@ -11,16 +11,17 @@ For information on downgrading an extension, see [Downgrade an Extension](downgr
 
 ## Prerequisites
 
-* You have an extension installed
+* You have a ClusterExtension installed
 * The target version is compatible with OLM v1 (see [OLM v1 limitations](../project/olmv1_limitations.md))
-* CRD compatibility between the versions being upgraded or downgraded (see [CRD upgrade safety](../concepts/crd-upgrade-safety.md))
-* The installer service account's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](../howto/derive-service-account.md))
+* Any changes to the CustomResourceDefinition in the new version meet compatibility requirements (see [CRD upgrade safety](../concepts/crd-upgrade-safety.md))
+* The installer ServiceAccount's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](../howto/derive-service-account.md))
+* You are not attempting to upgrade between minor versions with a major version of zero (see [Upgrades within the major version zero](../concepts/upgrade-support.md#upgrades-within-the-major-version-zero))
 
 For more detailed information see [Upgrade Support](../concepts/upgrade-support.md).
 
 ## Procedure
 
-Suppose we have successfully created and installed v0.5.0 of the ArgoCD operator with the following `ClusterExtension`:
+Suppose we have successfully created and installed v0.2.0 of the ArgoCD operator with the following `ClusterExtension`:
 
 ``` yaml title="Example CR"
 apiVersion: olm.operatorframework.io/v1
@@ -35,7 +36,7 @@ spec:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
-      version: 0.5.0
+      version: 0.2.0
 ```
 
 * Update the version field in the ClusterExtension resource:
@@ -54,7 +55,7 @@ spec:
         sourceType: Catalog
         catalog:
           packageName: argocd-operator
-          version: 0.6.0 # Update to version 0.6.0
+          version: 0.2.1 # Update to version 0.2.1
     EOF
     ```
 
@@ -66,27 +67,14 @@ spec:
     Alternatively, you can use `kubectl patch` to update the version field:
 
     ``` terminal
-    kubectl patch clusterextension <extension_name> --type='merge' -p '{"spec": {"source": {"catalog": {"version": "<target_version>"}}}}'
-    ```
-
-    `extension_name`
-    : Specifies the name defined in the `metadata.name` field of the extension's CR.
-
-    `target_version`
-    : Specifies the version to upgrade or downgrade to.
-
-    For example:
-    ``` terminal
-    kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.6.0"}}}}'
+    kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.2.1"}}}}'
     ```
 
     !!! success
         ``` text title="Example output"
         clusterextension.olm.operatorframework.io/argocd patched
         ```
 
-### Verification
-
 * Verify that the Kubernetes extension is updated:
 
     ``` terminal
@@ -100,15 +88,15 @@ spec:
         metadata:
           annotations:
             kubectl.kubernetes.io/last-applied-configuration: |
-              {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"argocd"},"spec":{"namespace":"argocd","serviceAccount":{"name":"argocd-installer"},"source":{"catalog":{"packageName":"argocd-operator","version":"0.5.0"},"sourceType":"Catalog"}}}
-          creationTimestamp: "2024-11-11T14:13:12Z"
+              {"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"argocd"},"spec":{"namespace":"argocd","serviceAccount":{"name":"argocd-installer"},"source":{"catalog":{"packageName":"argocd-operator","version":"0.2.1"},"sourceType":"Catalog"}}}
+          creationTimestamp: "2024-11-15T19:29:34Z"
           finalizers:
           - olm.operatorframework.io/cleanup-unpack-cache
           - olm.operatorframework.io/cleanup-contentmanager-cache
           generation: 2
           name: argocd
-          resourceVersion: "3289"
-          uid: 20f12bf4-76eb-457d-bbac-d28416c18a30
+          resourceVersion: "7274"
+          uid: 9af8e5f8-ae3d-4231-b15c-e63c62619db7
         spec:
           namespace: argocd
           serviceAccount:
@@ -117,49 +105,49 @@ spec:
             catalog:
               packageName: argocd-operator
               upgradeConstraintPolicy: CatalogProvided
-              version: 0.6.0
+              version: 0.2.1
             sourceType: Catalog
         status:
           conditions:
-          - lastTransitionTime: "2024-11-11T14:13:12Z"
+          - lastTransitionTime: "2024-11-15T19:29:34Z"
             message: ""
             observedGeneration: 2
             reason: Deprecated
             status: "False"
             type: Deprecated
-          - lastTransitionTime: "2024-11-11T14:13:12Z"
+          - lastTransitionTime: "2024-11-15T19:29:34Z"
             message: ""
             observedGeneration: 2
             reason: Deprecated
             status: "False"
             type: PackageDeprecated
-          - lastTransitionTime: "2024-11-11T14:13:12Z"
+          - lastTransitionTime: "2024-11-15T19:29:34Z"
             message: ""
             observedGeneration: 2
             reason: Deprecated
             status: "False"
             type: ChannelDeprecated
-          - lastTransitionTime: "2024-11-11T14:13:12Z"
+          - lastTransitionTime: "2024-11-15T19:29:34Z"
             message: ""
             observedGeneration: 2
             reason: Deprecated
             status: "False"
             type: BundleDeprecated
-          - lastTransitionTime: "2024-11-11T14:13:18Z"
-            message: Installed bundle quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3
+          - lastTransitionTime: "2024-11-15T19:29:37Z"
+            message: Installed bundle quay.io/operatorhubio/argocd-operator@sha256:e1cfacacf891fb243ded2bcd449a4f5c76f3230bf96a4de32734a87303e087c8
               successfully
             observedGeneration: 2
             reason: Succeeded
             status: "True"
             type: Installed
-          - lastTransitionTime: "2024-11-11T14:13:19Z"
+          - lastTransitionTime: "2024-11-15T19:29:37Z"
             message: desired state reached
             observedGeneration: 2
             reason: Succeeded
             status: "True"
             type: Progressing
           install:
             bundle:
-              name: argocd-operator.v0.6.0
-              version: 0.6.0
+              name: argocd-operator.v0.2.1
+              version: 0.2.1
         ```
