Merge pull request #57250 from jeana-redhat/OSDOCS-5528-ccoctl-upgrade-alibaba

[OSDOCS-5528]: Incorporate ccoctl upgrade steps for AliCloud

Author: jeana-redhat

_topic_maps/_topic_map.yml

@@ -569,7 +569,7 @@ Topics:
 - Name: Configuring additional devices in an IBM zSystems or IBM LinuxONE environment
   File: ibmz-post-install
 - Name: Regions and zones for a VMware vCenter
-  File: post-install-vsphere-zones-regions-configuration 
+  File: post-install-vsphere-zones-regions-configuration
 - Name: Red Hat Enterprise Linux CoreOS image layering
   File: coreos-layering
   Distros: openshift-enterprise
@@ -597,6 +597,8 @@ Topics:
   Distros: openshift-origin
 - Name: Preparing to perform an EUS-to-EUS update
   File: preparing-eus-eus-upgrade
+- Name: Preparing to update a cluster with manually maintained credentials
+  File: preparing-manual-creds-update
 - Name: Updating a cluster using the web console
   File: updating-cluster-within-minor
 - Name: Updating a cluster using the CLI
@@ -3875,7 +3877,7 @@ Topics:
     - Name: Resolving image tags to digests
       File: resolving-image-tags-to-digests
     - Name: Configuring TLS authentication
-      File: serverless-config-tls      
+      File: serverless-config-tls
     - Name: Restrictive network policies
       File: restrictive-network-policies
   - Name: Traffic splitting

authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc

@@ -10,17 +10,12 @@ The Cloud Credential Operator (CCO) manages cloud provider credentials as  custo
 
 By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in several different modes. If no mode is specified, or the `credentialsMode` parameter is set to an empty string (`""`), the CCO operates in its default mode.
 
-[id="about-cloud-credential-operator-modes"]
+[id="about-cloud-credential-operator-modes_{context}"]
 == Modes
 
 By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in _mint_, _passthrough_, or _manual_ mode. These options provide transparency and flexibility in how the CCO uses cloud credentials to process `CredentialsRequest` CRs in the cluster, and allow the CCO to be configured to suit the security requirements of your organization. Not all CCO modes are supported for all cloud providers.
 
 * **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-mint.adoc#cco-mode-mint[Mint]**: In mint mode, the CCO uses the provided admin-level cloud credential to create new credentials for components in the cluster with only the specific permissions that are required.
-+
-[NOTE]
-====
-Mint mode is the default and recommended best practice setting for the CCO to use.
-====
 
 * **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-passthrough.adoc#cco-mode-passthrough[Passthrough]**: In passthrough mode, the CCO passes the provided cloud credential to the components that request cloud credentials.
 
@@ -82,7 +77,22 @@ Mint mode is the default and recommended best practice setting for the CCO to us
 1. Manual mode is the only supported CCO configuration for Microsoft Azure Stack Hub.
 --
 
-[id="about-cloud-credential-operator-default"]
+[id="cco-determine-mode_{context}"]
+== Determining the Cloud Credential Operator mode
+
+For platforms that support using the CCO in multiple modes, you can determine what mode the CCO is configured to use by using the web console or the CLI.
+
+//To-do: add this in when available (gfx request #334)
+//.[PLACEHOLDER] Determining the CCO configuration
+//image::placeholder_CCO_decision_tree_about_cco.png[Decision tree showing how to determine the configured CCO credentials mode for your cluster.]
+
+//Determining the Cloud Credential Operator mode by using the web console
+include::modules/cco-determine-mode-gui.adoc[leveloffset=+2]
+
+//Determining the Cloud Credential Operator mode by using the CLI
+include::modules/cco-determine-mode-cli.adoc[leveloffset=+2]
+
+[id="about-cloud-credential-operator-default_{context}"]
 == Default behavior
 For platforms on which multiple modes are supported (AWS, Azure, and GCP), when the CCO operates in its default mode, it checks the provided credentials dynamically to determine for which mode they are sufficient to process `CredentialsRequest` CRs.
 
@@ -95,7 +105,7 @@ If the credentials are changed after a successful installation and the CCO deter
 To resolve insufficient credentials issues, provide a credential with sufficient permissions. If an error occurred during installation, try installing again. For issues with new `CredentialsRequest` CRs, wait for the CCO to try to process the CR again. As an alternative, you can manually create IAM for xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], and xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[GCP].
 
 [role="_additional-resources"]
-[id="additional-resources_about-cloud-credential-operator"]
+[id="additional-resources_about-cloud-credential-operator_{context}"]
 == Additional resources
 
 * xref:../../operators/operator-reference.adoc#cloud-credential-operator_cluster-operators-ref[Cluster Operators reference page for the Cloud Credential Operator]

authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc

@@ -97,13 +97,15 @@ To install a cluster that is configured to use the Cloud Credential Operator (CC
 . xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#sts-mode-installing-manual-run-installer_cco-mode-gcp-workload-identity[Run the {product-title} installer].
 . xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#sts-mode-installing-verifying_cco-mode-gcp-workload-identity[Verify that the cluster is using short-lived credentials].
 
-////
-// Remove until upgrade is supported.
 [NOTE]
 ====
 Because the cluster is operating in manual mode when using GCP Workload Identity, it is not able to create new credentials for components with the permissions that they require. When upgrading to a different minor version of {product-title}, there are often new GCP permission requirements. Before upgrading a cluster that is using GCP Workload Identity, the cluster administrator must manually ensure that the GCP permissions are sufficient for existing components and available to any new components.
 ====
-////
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../updating/preparing-manual-creds-update.adoc#cco-ccoctl-configuring_preparing-manual-creds-update[Configuring the Cloud Credential Operator utility for a cluster update]
 
 //Task part 1: Configuring the Cloud Credential Operator utility
 include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
@@ -117,17 +119,8 @@ include::modules/sts-mode-installing-manual-run-installer.adoc[leveloffset=+2]
 //Task part 4: Verify that the cluster is using short-lived credentials
 include::modules/sts-mode-installing-verifying.adoc[leveloffset=+2]
 
-[id="gcp-workload-identity-mode-upgrading"]
-== Upgrading an {product-title} cluster configured for manual mode with GCP Workload Identity
-
-The release image for the version of {product-title} that you are upgrading to contains a version of the `ccoctl` binary and list of `CredentialsRequest` objects specific to that release.
-
-:context: wif-mode-upgrading
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
 
-include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
-
-include::modules/cco-ccoctl-upgrading.adoc[leveloffset=+2]
-
-include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+2]
-
-:context: cco-mode-gcp-workload-identity
+* xref:../../updating/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]

authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc

@@ -12,22 +12,37 @@ In manual mode, a user manages cloud credentials instead of the Cloud Credential
 
 Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. This mode also does not require connectivity to the AWS public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade.
 
-For information about configuring your cloud provider to use manual mode, see _Manually creating RAM resources_ for xref:../../installing/installing_alibaba/installing-alibaba-default.adoc#installation-initializing_installing-alibaba-default[Alibaba Cloud], xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], xref:../../installing/installing_ibm_cloud_public/configuring-iam-ibm-cloud.adoc#configuring-iam-ibm-cloud[IBM Cloud], or xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[GCP].
+For information about configuring your cloud provider to use manual mode, see the manual credentials management options for your cloud provider:
+
+* xref:../../installing/installing_alibaba/manually-creating-alibaba-ram.adoc#manually-creating-alibaba-ram[Manually creating RAM resources for Alibaba Cloud]
+* xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS]
+* xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating IAM for Azure]
+* xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[Manually creating IAM for GCP]
+* xref:../../installing/installing_ibm_cloud_public/configuring-iam-ibm-cloud.adoc#configuring-iam-ibm-cloud[Configuring IAM for IBM Cloud]
+* xref:../../installing/installing_nutanix/installing-nutanix-installer-provisioned.adoc#manually-create-iam-nutanix_installing-nutanix-installer-provisioned[Configuring IAM for Nutanix]
 
 [id="manual-mode-sts-blurb"]
-== Manual mode with AWS STS
+== Manual mode with cloud credentials created and managed outside of the cluster
 
-You can configure an AWS cluster in manual mode to use xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Amazon Web Services Security Token Service (AWS STS)]. With this configuration, the CCO uses temporary credentials for different components.
+An AWS or GCP cluster that uses manual mode might be configured to create and manage cloud credentials from outside of the cluster using the AWS Security Token Service (STS) or GCP Workload Identity. With this configuration, the CCO uses temporary credentials for different components.
 
+For more information, see xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Using manual mode with Amazon Web Services Security Token Service] or xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#cco-mode-gcp-workload-identity[Using manual mode with GCP Workload Identity].
+
+//Updating cloud provider resources with manually maintained credentials
 include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1]
 
+//Indicating that the cluster is ready to upgrade
+include::modules/cco-manual-upgrade-annotation.adoc[leveloffset=+2]
+
 [role="_additional-resources"]
 [id="additional-resources_cco-mode-manual"]
 == Additional resources
 
 * xref:../../installing/installing_alibaba/manually-creating-alibaba-ram.adoc#manually-creating-alibaba-ram[Manually creating RAM resources for Alibaba Cloud]
 * xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS]
+* xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Using manual mode with Amazon Web Services Security Token Service]
 * xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating IAM for Azure]
 * xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[Manually creating IAM for GCP]
+* xref:../../authentication/managing_cloud_provider_credentials/cco-mode-gcp-workload-identity.adoc#cco-mode-gcp-workload-identity[Using manual mode with GCP Workload Identity]
 * xref:../../installing/installing_ibm_cloud_public/configuring-iam-ibm-cloud.adoc#configuring-iam-ibm-cloud[Configuring IAM for IBM Cloud]
-* xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Using manual mode with AWS STS]
+* xref:../../installing/installing_nutanix/installing-nutanix-installer-provisioned.adoc#manually-create-iam-nutanix_installing-nutanix-installer-provisioned[Configuring IAM for Nutanix]

authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc

@@ -13,7 +13,7 @@ Manual mode with STS is supported for Amazon Web Services (AWS).
 This credentials strategy is supported for only new {product-title} clusters and must be configured during installation. You cannot reconfigure an existing cluster that uses a different credentials strategy to use this feature.
 ====
 
-[id="sts-mode-about"]
+[id="sts-mode-about_{context}"]
 == About manual mode with AWS Security Token Service
 
 In manual mode with STS, the individual {product-title} cluster components use AWS Security Token Service (STS) to assign components IAM roles that provide short-term, limited-privilege security credentials. These credentials are associated with IAM roles that are specific to each component that makes AWS API calls.
@@ -66,7 +66,7 @@ stringData:
 <4> The path to the service account token inside the pod. By convention, this is `/var/run/secrets/openshift/serviceaccount/token` for {product-title} components.
 
 //Supertask: Installing an OCP cluster configured for manual mode with STS
-[id="sts-mode-installing"]
+[id="sts-mode-installing_{context}"]
 == Installing an {product-title} cluster configured for manual mode with STS
 
 To install a cluster that is configured to use the Cloud Credential Operator (CCO) in manual mode with STS:
@@ -82,13 +82,18 @@ To install a cluster that is configured to use the Cloud Credential Operator (CC
 Because the cluster is operating in manual mode when using STS, it is not able to create new credentials for components with the permissions that they require. When upgrading to a different minor version of {product-title}, there are often new AWS permission requirements. Before upgrading a cluster that is using STS, the cluster administrator must manually ensure that the AWS permissions are sufficient for existing components and available to any new components.
 ====
 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../updating/preparing-manual-creds-update.adoc#cco-ccoctl-configuring_preparing-manual-creds-update[Configuring the Cloud Credential Operator utility for a cluster update]
+
 //[pre-4.8]Task part 1: Creating AWS resources manually
 //include::modules/sts-mode-installing-manual-config.adoc[leveloffset=+2]
 
 //Task part 1: Configuring the Cloud Credential Operator utility
 include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
 
-[id="sts-mode-create-aws-resources-ccoctl"]
+[id="sts-mode-create-aws-resources-ccoctl_{context}"]
 === Creating AWS resources with the Cloud Credential Operator utility
 
 You can use the CCO utility (`ccoctl`) to create the required AWS resources xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-ccoctl-creating-individually_cco-mode-sts[individually], or xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-ccoctl-creating-at-once_cco-mode-sts[with a single command].
@@ -105,17 +110,8 @@ include::modules/sts-mode-installing-manual-run-installer.adoc[leveloffset=+2]
 //Task part 4: Verify that the cluster is using short-lived credentials
 include::modules/sts-mode-installing-verifying.adoc[leveloffset=+2]
 
-[id="sts-mode-upgrading"]
-== Upgrading an {product-title} cluster configured for manual mode with STS
-
-The release image for the version of {product-title} that you are upgrading to contains a version of the `ccoctl` binary and list of `CredentialsRequest` objects specific to that release.
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
 
-:context: sts-mode-upgrading
-
-include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
-
-include::modules/cco-ccoctl-upgrading.adoc[leveloffset=+2]
-
-include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+2]
-
-:context: cco-mode-sts
+* xref:../../updating/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]

installing/installing_alibaba/manually-creating-alibaba-ram.adoc

@@ -16,6 +16,9 @@ include::modules/manually-creating-alibaba-ram-user.adoc[leveloffset=+1]
 
 //Task part 2: Configuring the Cloud Credential Operator utility
 include::modules/cco-ccoctl-configuring.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../updating/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]
 
 //Task part 3: Creating Alibaba resources with a single command
 // modules/cco-ccoctl-creating-at-once.adoc[leveloffset=+1]

installing/installing_azure_stack_hub/installing-azure-stack-hub-default.adoc

@@ -39,8 +39,7 @@ include::modules/manually-create-identity-access-management.adoc[leveloffset=+1]
 [role="_additional-resources"]
 [id="additional-resources_installing-azure-stack-hub-default-cco"]
 .Additional resources
-* xref:../../updating/updating-cluster-within-minor.adoc#manually-maintained-credentials-upgrade_updating-cluster-within-minor[Updating a cluster using the web console]
-* xref:../../updating/updating-cluster-cli.adoc#manually-maintained-credentials-upgrade_updating-cluster-cli[Updating a cluster using the CLI]
+* xref:../../updating/preparing-manual-creds-update.adoc#manually-maintained-credentials-upgrade_preparing-manual-creds-update[Updating cloud provider resources with manually maintained credentials]
 
 include::modules/azure-stack-hub-internal-ca.adoc[leveloffset=+1]
 

installing/installing_azure_stack_hub/manually-creating-iam-azure-stack-hub.adoc

@@ -22,6 +22,7 @@ include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[level
 
 include::modules/manually-create-identity-access-management.adoc[leveloffset=+1]
 
+// I was going to update this but I think the assembly is no longer used and will ask install team if I can get rid of it entirely.
 include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1]
 
 [id="next-steps_manually-creating-iam-azure-stack-hub"]

installing/installing_ibm_cloud_public/configuring-iam-ibm-cloud.adoc

@@ -16,8 +16,6 @@ include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[level
 * xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc#about-cloud-credential-operator[About the Cloud Credential Operator]
 
 include::modules/cco-ccoctl-configuring.adoc[leveloffset=+1]
-//include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1]
-// Will need to revisit upgrade scenario for IBM Cloud; not needed until OCP 4.11. Tentative instructions have been added for reference later.
 
 [role="_additional-resources"]
 [id="additional-resources_configuring-iam-ibm-cloud-refreshing-ids"]
@@ -27,3 +25,9 @@ include::modules/cco-ccoctl-configuring.adoc[leveloffset=+1]
 [id="next-steps_configuring-iam-ibm-cloud"]
 == Next steps
 * xref:../../installing/installing_ibm_cloud_public/installing-ibm-cloud-customizations.adoc#installing-ibm-cloud-customizations[Installing a cluster on IBM Cloud VPC with customizations]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* xref:../../updating/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]

installing/installing_nutanix/preparing-to-install-on-nutanix.adoc

@@ -11,3 +11,6 @@ Before you install an {product-title} cluster, be sure that your Nutanix environ
 include::modules/installation-nutanix-infrastructure.adoc[leveloffset=+1]
 include::modules/installation-nutanix-installer-infra-reqs.adoc[leveloffset=+1]
 include::modules/cco-ccoctl-configuring.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+* xref:../../updating/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]