Merge pull request #36182 from jeana-redhat/CCO-15_manual-mode-annotation

CCO-15: update process for upgrading manually maintained creds

Author: jeana-redhat

modules/manually-maintained-credentials-upgrade.adoc

@@ -8,20 +8,59 @@
 [id="manually-maintained-credentials-upgrade_{context}"]
 = Upgrading clusters with manually maintained credentials
 
-If credentials are added in a future release, the Cloud Credential Operator (CCO) `upgradable` status for a cluster with manually maintained credentials changes to `false`. For minor release, for example, from 4.7 to 4.8, this status prevents you from upgrading until you have addressed any updated permissions. For z-stream releases, for example, from 4.7.12 to 4.7.13, the upgrade is not blocked, but the credentials must still be updated for the new release.
+The Cloud Credential Operator (CCO) `Upgradable` status for a cluster with manually maintained credentials is `False` by default.
 
-Use the *Administrator* perspective of the web console to determine if the CCO is upgradeable.
+//to-do: update "from 4.7 to 4.8" to "from 4.8 to 4.9" when 4.9 is released
+* For minor releases, for example, from 4.7 to 4.8, this status prevents you from upgrading until you have addressed any updated permissions and annotated the `CloudCredential` resource to indicate that the permissions are updated as needed for the next version. This annotation changes the `Upgradable` status to `True`.
 
-. Navigate to *Administration* -> *Cluster Settings*.
+* For z-stream releases, for example, from 4.8.9 to 4.8.10, no permissions are added or changed, so the upgrade is not blocked.
 
-. To view the CCO status details, click *cloud-credential* in the *Cluster Operators* list.
+Before upgrading a cluster with manually maintained credentials, you must create any new credentials for the release image that you are upgrading to. Additionally, you must review the required permissions for existing credentials and accommodate any new permissions requirements in the new release for those components.
 
-. If the *Upgradeable* status in the *Conditions* section is *False*, examine the `CredentialsRequest` custom resource for the new release and update the manually maintained credentials on your cluster to match before upgrading.
-
-In addition to creating new credentials for the release image that you are
-upgrading to, you must review the required permissions for existing credentials
-and accommodate any new permissions requirements for existing components in the
-new release. The CCO cannot detect these mismatches and will not set
-`upgradable` to `false` in this case.
+.Procedure
 
+. Extract and examine the `CredentialsRequest` custom resource for the new release.
++
 The _Manually creating IAM_ section of the installation content for your cloud provider explains how to obtain and use the credentials required for your cloud.
+
+. Update the manually maintained credentials on your cluster:
+
+** Create new secrets for any `CredentialsRequest` custom resources that are added by the new release image.
+
+** If the `CredentialsRequest` custom resources for any existing credentials that are stored in secrets have changed their permissions requirements, update the permissions as required.
+
+. When all of the secrets are correct for the new release, indicate that the cluster is ready to upgrade:
+
+.. Log in to the {product-title} CLI as a user with the `cluster-admin` role.
+
+.. Edit the `CloudCredential` resource to add an `upgradeable-to` annotation within the `metadata` field:
++
+[source,terminal]
+----
+$ oc edit cloudcredential cluster
+----
++
+.Text to add
++
+[source,yaml]
+----
+...
+  metadata:
+    annotations:
+      cloudcredential.openshift.io/upgradeable-to: <version_number>
+...
+----
++
+Where `<version_number>` is the version you are upgrading to, in the format `x.y.z`. For example, `4.8.2` for {product-title} 4.8.2.
++
+It may take several minutes after adding the annotation for the upgradeable status to change.
+
+. Verify that the CCO is upgradeable:
+
+.. In the the *Administrator* perspective of the web console, navigate to *Administration* -> *Cluster Settings*.
+
+.. To view the CCO status details, click *cloud-credential* in the *Cluster Operators* list.
+
+.. If the *Upgradeable* status in the *Conditions* section is *False*, verify that the `upgradeable-to` annotation is free of typographical errors.
+
+When the *Upgradeable* status in the *Conditions* section is *True*, you can begin the {product-title} upgrade.