[OSDOCS-6135]: Configuring an Azure cluster with short-term creds

Author: jeana-redhat

_topic_maps/_topic_map.yml

@@ -199,8 +199,6 @@ Topics:
     File: preparing-to-install-on-azure
   - Name: Configuring an Azure account
     File: installing-azure-account
-  - Name: Manually creating long-term credentials for Azure
-    File: manually-creating-iam-azure
   - Name: Enabling user-managed encryption on Azure
     File: enabling-user-managed-encryption-azure
   - Name: Installing a cluster quickly on Azure

installing/installing_azure/manually-creating-iam-azure.adoc renamed to _unused_topics/manually-creating-iam-azure.adoc

@@ -28,7 +28,7 @@ An AWS, global Azure, or GCP cluster that uses manual mode might be configured t
 
 * xref:../../installing/installing_alibaba/manually-creating-alibaba-ram.adoc#manually-creating-alibaba-ram[Manually creating RAM resources for Alibaba Cloud]
 * xref:../../installing/installing_aws/installing-aws-customizations.adoc#manually-create-iam_installing-aws-customizations[Manually creating long-term credentials for AWS]
-* xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating long-term credentials for Azure]
+* xref:../../installing/installing_azure/installing-azure-customizations.adoc#manually-create-iam_installing-azure-customizations[Manually creating long-term credentials for Azure]
 * xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#manually-create-iam_installing-gcp-customizations[Manually creating long-term credentials 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]

authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc

@@ -29,7 +29,7 @@ To locate the `CredentialsRequest` CRs that are required, see xref:../../install
 === Microsoft Azure permissions
 The credential you provide for passthrough mode in Azure must have all the requested permissions for all `CredentialsRequest` CRs that are required by the version of {product-title} you are running or installing.
 
-To locate the `CredentialsRequest` CRs that are required, see xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating long-term credentials for Azure].
+To locate the `CredentialsRequest` CRs that are required, see xref:../../installing/installing_azure/installing-azure-customizations.adoc#manually-create-iam_installing-azure-customizations[Manually creating long-term credentials for Azure].
 
 [id="passthrough-mode-permissions-gcp"]
 === Google Cloud Platform (GCP) permissions
@@ -81,7 +81,7 @@ include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1]
 
 [id="passthrough-mode-maintenance"]
 == Passthrough mode credential maintenance
-If `CredentialsRequest` CRs change over time as the cluster is upgraded, you must manually update the passthrough mode credential to meet the requirements. To avoid credentials issues during an upgrade, check the `CredentialsRequest` CRs in the release image for the new version of {product-title} before upgrading. To locate the `CredentialsRequest` CRs that are required for your cloud provider, see _Manually creating long-term credentials_ for xref:../../installing/installing_aws/installing-aws-customizations.adoc#manually-create-iam_installing-aws-customizations[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], or xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#manually-create-iam_installing-gcp-customizations[GCP].
+If `CredentialsRequest` CRs change over time as the cluster is upgraded, you must manually update the passthrough mode credential to meet the requirements. To avoid credentials issues during an upgrade, check the `CredentialsRequest` CRs in the release image for the new version of {product-title} before upgrading. To locate the `CredentialsRequest` CRs that are required for your cloud provider, see _Manually creating long-term credentials_ for xref:../../installing/installing_aws/installing-aws-customizations.adoc#manually-create-iam_installing-aws-customizations[AWS], xref:../../installing/installing_azure/installing-azure-customizations.adoc#manually-create-iam_installing-azure-customizations[Azure], or xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#manually-create-iam_installing-gcp-customizations[GCP].
 
 //Rotating cloud provider credentials manually
 include::modules/manually-rotating-cloud-creds.adoc[leveloffset=+2]
@@ -96,11 +96,11 @@ When using passthrough mode, each component has the same permissions used by all
 
 After installation, you can reduce the permissions on your credential to only those that are required to run the cluster, as defined by the `CredentialsRequest` CRs in the release image for the version of {product-title} that you are using.
 
-To locate the `CredentialsRequest` CRs that are required for AWS, Azure, or GCP and learn how to change the permissions the CCO uses, see _Manually creating long-term credentials_ for xref:../../installing/installing_aws/installing-aws-customizations.adoc#manually-create-iam_installing-aws-customizations[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], or xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#manually-create-iam_installing-gcp-customizations[GCP].
+To locate the `CredentialsRequest` CRs that are required for AWS, Azure, or GCP and learn how to change the permissions the CCO uses, see _Manually creating long-term credentials_ for xref:../../installing/installing_aws/installing-aws-customizations.adoc#manually-create-iam_installing-aws-customizations[AWS], xref:../../installing/installing_azure/installing-azure-customizations.adoc#manually-create-iam_installing-azure-customizations[Azure], or xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#manually-create-iam_installing-gcp-customizations[GCP].
 
 [role="_additional-resources"]
 == Additional resources
 
 * xref:../../installing/installing_aws/installing-aws-customizations.adoc#manually-create-iam_installing-aws-customizations[Manually creating long-term credentials for AWS]
-* xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating long-term credentials for Azure]
+* xref:../../installing/installing_azure/installing-azure-customizations.adoc#manually-create-iam_installing-azure-customizations[Manually creating long-term credentials for Azure]
 * xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#manually-create-iam_installing-gcp-customizations[Manually creating long-term credentials for GCP]

authentication/managing_cloud_provider_credentials/cco-mode-passthrough.adoc

@@ -84,7 +84,7 @@ In manual mode with Azure AD Workload Identity, the individual {product-title} c
 
 [role="_additional-resources"]
 .Additional resources
-//* xr\ef:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-with-short-term-creds_installing-azure-customizations[Configuring a global Microsoft Azure cluster to use short-term credentials]
+* xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-with-short-term-creds_installing-azure-customizations[Configuring a global Microsoft Azure cluster to use short-term credentials]
 
 //Azure AD Workload Identity authentication process (placeholder)
 //include::modules/cco-short-term-creds-auth-flow-azure.adoc[leveloffset=+2]
@@ -101,5 +101,5 @@ include::modules/cco-short-term-creds-component-permissions-azure.adoc[leveloffs
 
 * xref:../../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-with-short-term-creds_installing-aws-customizations[Configuring an AWS cluster to use short-term credentials]
 * xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-with-short-term-creds_installing-gcp-customizations[Configuring a GCP cluster to use short-term credentials]
-//* xr\ef:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-with-short-term-creds_installing-azure-customizations[Configuring a global Microsoft Azure cluster to use short-term credentials]
+* xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-with-short-term-creds_installing-azure-customizations[Configuring a global Microsoft Azure cluster to use short-term credentials]
 * xref:../../updating/preparing_for_updates/preparing-manual-creds-update.adoc#preparing-manual-creds-update[Preparing to update a cluster with manually maintained credentials]

authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc

@@ -39,7 +39,7 @@ include::modules/installation-creating-azure-service-principal.adoc[leveloffset=
 [role="_additional-resources"]
 .Additional resources
 
-* For more information about CCO modes, see xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc#about-cloud-credential-operator-modes[About the Cloud Credential Operator].
+* xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc#about-cloud-credential-operator-modes[About the Cloud Credential Operator]
 
 include::modules/installation-azure-marketplace.adoc[leveloffset=+1]
 

installing/installing_azure/installing-azure-account.adoc

@@ -18,7 +18,6 @@ parameters in the `install-config.yaml` file before you install the cluster.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[configured an Azure account] to host the cluster and determined the tested and validated region to deploy the cluster to.
 * If you use a firewall, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to.
-* If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually create and maintain IAM credentials].
 * If you use customer-managed encryption keys, you xref:../../installing/installing_azure/enabling-user-managed-encryption-azure.adoc#enabling-user-managed-encryption-azure[prepared your Azure environment for encryption].
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
@@ -59,10 +58,38 @@ include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 * For more details about Accelerated Networking, see xref:../../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-azure-accelerated-networking_creating-machineset-azure[Accelerated Networking for Microsoft Azure VMs].
 
-include::modules/installation-launching-installer.adoc[leveloffset=+1]
-
+//Installing the OpenShift CLI by downloading the binary: Moved up to precede manual cred (short and long) steps, which require the use of `oc`
 include::modules/cli-installing-cli.adoc[leveloffset=+1]
 
+[id="installing-azure-manual-modes_{context}"]
+== Alternatives to storing administrator-level secrets in the kube-system project
+
+By default, administrator secrets are stored in the `kube-system` project. If you configured the `credentialsMode` parameter in the `install-config.yaml` file to `Manual`, you must use one of the following alternatives:
+
+* To manage long-term cloud credentials manually, follow the procedure in xref:../../installing/installing_azure/installing-azure-customizations.adoc#manually-create-iam_installing-azure-customizations[Manually creating long-term credentials].
+
+* To implement short-term credentials that are managed outside the cluster for individual components, follow the procedures in xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-with-short-term-creds_installing-azure-customizations[Configuring an Azure cluster to use short-term credentials].
+
+//Manually creating long-term credentials
+include::modules/manually-create-identity-access-management.adoc[leveloffset=+2]
+
+//Supertask: Configuring an Azure cluster to use short-term credentials
+[id="installing-azure-with-short-term-creds_{context}"]
+=== Configuring an Azure cluster to use short-term credentials
+
+To install a cluster that uses Azure AD Workload Identity, you must configure the Cloud Credential Operator utility and create the required Azure resources for your cluster.
+
+//Task part 1: Configuring the Cloud Credential Operator utility
+include::modules/cco-ccoctl-configuring.adoc[leveloffset=+3]
+
+//Task part 2: Creating the required Azure resources
+include::modules/cco-ccoctl-creating-at-once.adoc[leveloffset=+3]
+
+// Additional steps for the Cloud Credential Operator utility (`ccoctl`)
+include::modules/cco-ccoctl-install-creating-manifests.adoc[leveloffset=+3]
+
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
+
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
 
 [role="_additional-resources"]

installing/installing_azure/installing-azure-customizations.adoc

@@ -17,7 +17,7 @@ cluster.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[configured an Azure account] to host the cluster and determined the tested and validated government region to deploy the cluster to.
 * If you use a firewall, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to.
-* If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually create and maintain IAM credentials].
+* If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_azure/installing-azure-customizations.adoc#manually-create-iam_installing-azure-customizations[manually create and maintain long-term credentials].
 * If you use customer-managed encryption keys, you xref:../../installing/installing_azure/enabling-user-managed-encryption-azure.adoc#enabling-user-managed-encryption-azure[prepared your Azure environment for encryption].
 
 include::modules/installation-azure-about-government-region.adoc[leveloffset=+1]

installing/installing_azure/installing-azure-government-region.adoc

@@ -22,7 +22,6 @@ cluster.
 * You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users].
 * You xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[configured an Azure account] to host the cluster and determined the tested and validated region to deploy the cluster to.
 * If you use a firewall, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to.
-* If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, you can xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually create and maintain IAM credentials]. Manual mode can also be used in environments where the cloud IAM APIs are not reachable.
 * If you use customer-managed encryption keys, you xref:../../installing/installing_azure/enabling-user-managed-encryption-azure.adoc#enabling-user-managed-encryption-azure[prepared your Azure environment for encryption].
 
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
@@ -69,10 +68,38 @@ For more information on using Linux and Windows nodes in the same cluster, see x
 
 * For more details about Accelerated Networking, see xref:../../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-azure-accelerated-networking_creating-machineset-azure[Accelerated Networking for Microsoft Azure VMs].
 
-include::modules/installation-launching-installer.adoc[leveloffset=+1]
-
+//Installing the OpenShift CLI by downloading the binary: Moved up to precede manual cred (short and long) steps, which require the use of `oc`
 include::modules/cli-installing-cli.adoc[leveloffset=+1]
 
+[id="installing-azure-manual-modes_{context}"]
+== Alternatives to storing administrator-level secrets in the kube-system project
+
+By default, administrator secrets are stored in the `kube-system` project. If you configured the `credentialsMode` parameter in the `install-config.yaml` file to `Manual`, you must use one of the following alternatives:
+
+* To manage long-term cloud credentials manually, follow the procedure in xref:../../installing/installing_azure/installing-azure-network-customizations.adoc#manually-create-iam_installing-azure-network-customizations[Manually creating long-term credentials].
+
+* To implement short-term credentials that are managed outside the cluster for individual components, follow the procedures in xref:../../installing/installing_azure/installing-azure-network-customizations.adoc#installing-azure-with-short-term-creds_installing-azure-network-customizations[Configuring an Azure cluster to use short-term credentials].
+
+//Manually creating long-term credentials
+include::modules/manually-create-identity-access-management.adoc[leveloffset=+2]
+
+//Supertask: Configuring an Azure cluster to use short-term credentials
+[id="installing-azure-with-short-term-creds_{context}"]
+=== Configuring an Azure cluster to use short-term credentials
+
+To install a cluster that uses Azure AD Workload Identity, you must configure the Cloud Credential Operator utility and create the required Azure resources for your cluster.
+
+//Task part 1: Configuring the Cloud Credential Operator utility
+include::modules/cco-ccoctl-configuring.adoc[leveloffset=+3]
+
+//Task part 2: Creating the required Azure resources
+include::modules/cco-ccoctl-creating-at-once.adoc[leveloffset=+3]
+
+// Additional steps for the Cloud Credential Operator utility (`ccoctl`)
+include::modules/cco-ccoctl-install-creating-manifests.adoc[leveloffset=+3]
+
+include::modules/installation-launching-installer.adoc[leveloffset=+1]
+
 include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1]
 
 [role="_additional-resources"]