OSDOCS-17075_a: CCO CQA updates

modules/about-manually-maintained-credentials-upgrade.adoc

@@ -7,6 +7,7 @@
 [id="about-manually-maintained-credentials-upgrade_{context}"]
 = Update requirements for clusters with manually maintained credentials
 
+[role="_abstract"]
 Before you update a cluster that uses manually maintained credentials with the Cloud Credential Operator (CCO), you must update the cloud provider resources for the new release.
 
 If the cloud credential management for your cluster was configured using the CCO utility (`ccoctl`), use the `ccoctl` utility to update the resources. Clusters that were configured to use manual mode without the `ccoctl` utility require manual updates for the resources.

modules/cco-ccoctl-upgrading.adoc

@@ -1,8 +1,3 @@
-// Module included in the following assemblies:
-//
-// * updating/preparing_for_updates/preparing-manual-creds-update.adoc
-
-
 :_mod-docs-content-type: PROCEDURE
 [id="cco-ccoctl-upgrading_{context}"]
 = Updating cloud provider resources with the Cloud Credential Operator utility
@@ -43,97 +38,103 @@ $ oc get secret bound-service-account-signing-key \
 . Use the `ccoctl` tool to process all `CredentialsRequest` objects by running the command for your cloud provider. The following commands process `CredentialsRequest` objects:
 +
 .Amazon Web Services (AWS)
-[%collapsible]
-====
 [source,terminal]
 ----
-$ ccoctl aws create-all \// <1>
-  --name=<name> \// <2>
-  --region=<aws_region> \// <3>
-  --credentials-requests-dir=<path_to_credentials_requests_directory> \// <4>
-  --output-dir=<path_to_ccoctl_output_dir> \// <5>
-  --public-key-file=<path_to_ccoctl_output_dir>/serviceaccount-signer.public \// <6>
-  --create-private-s3-bucket \// <7>
-  --permissions-boundary-arn=<policy_arn> <8>
-----
-<1> To create the AWS resources individually, use the "Creating AWS resources individually" procedure in the "Installing a cluster on AWS with customizations" content. This option might be useful if you need to review the JSON files that the `ccoctl` tool creates before modifying AWS resources, or if the process the `ccoctl` tool uses to create AWS resources automatically does not meet the requirements of your organization.
-<2> Specify the name used to tag any cloud resources that are created for tracking.
-<3> Specify the AWS region in which cloud resources will be created.
-<4> Specify the directory containing the files for the component `CredentialsRequest` objects.
-<5> Specify the path to the output directory.
-<6> Specify the path to the `serviceaccount-signer.public` file that you extracted from the cluster.
-<7> Optional: By default, the `ccoctl` utility stores the OpenID Connect (OIDC) configuration files in a public S3 bucket and uses the S3 URL as the public OIDC endpoint. To store the OIDC configuration in a private S3 bucket that is accessed by the IAM identity provider through a public CloudFront distribution URL instead, use the `--create-private-s3-bucket` parameter.
-<8> Optional: Specify the Amazon Resource Name (ARN) of the {aws-short} IAM policy to use as the permissions boundary for the IAM roles created by the `ccoctl` utility.
+$ ccoctl aws create-all \
+  --name=<name> \//
+  --region=<aws_region> \
+  --credentials-requests-dir=<path_to_credentials_requests_directory> \
+  --output-dir=<path_to_ccoctl_output_dir> \
+  --public-key-file=
+  <path_to_ccoctl_output_dir>/serviceaccount-signer.public \
+  --create-private-s3-bucket
+  --permissions-boundary-arn=<policy_arn>
+----
++
+where:
+
+`<name>`:: Specifies the name used to tag any cloud resources that are created for tracking.
+`<aws_region>`:: Specifies the AWS region in which cloud resources will be created.
+`<path_to_credentials_requests_directory>`:: Specifies the directory containing the files for the component `CredentialsRequest` objects.
+`<path_to_ccoctl_output_dir>`:: Specifies the path to the output directory.
+`<path_to_ccoctl_output_dir>/serviceaccount-signer.public`:: Specifies the path to the `serviceaccount-signer.public` file that you extracted from the cluster.
+
+[NOTE]
+====
+To create the AWS resources individually, use the "Creating AWS resources individually" procedure in the "Installing a cluster on AWS with customizations" content. This option might be useful if you need to review the JSON files that the `ccoctl` tool creates before modifying AWS resources, or if the process the `ccoctl` tool uses to create AWS resources automatically does not meet the requirements of your organization.
+
+By default, the `ccoctl` utility stores the OpenID Connect (OIDC) configuration files in a public S3 bucket and uses the S3 URL as the public OIDC endpoint. To store the OIDC configuration in a private S3 bucket that is accessed by the IAM identity provider through a public CloudFront distribution URL instead, use the `--create-private-s3-bucket` parameter. This is an optional parameter.
 ====
+
+`<policy_arn>`:: Specifies the Amazon Resource Name (ARN) of the {aws-short} IAM policy to use as the permissions boundary for the IAM roles created by the `ccoctl` utility. This is optional parameter.
 +
 .{gcp-first}
-[%collapsible]
-====
 [source,terminal]
 ----
 $ ccoctl gcp create-all \
-  --name=<name> \// <1>
-  --region=<gcp_region> \// <2>
-  --project=<gcp_project_id> \// <3>
-  --credentials-requests-dir=<path_to_credentials_requests_directory> \// <4>
-  --output-dir=<path_to_ccoctl_output_dir> \// <5>
-  --public-key-file=<path_to_ccoctl_output_dir>/serviceaccount-signer.public \// <6>
-  --key-storage-method=<key_storage_method> <7>
-----
-<1> Specify the user-defined name for all created {gcp-short} resources used for tracking.
-<2> Specify the {gcp-short} region in which cloud resources will be created.
-<3> Specify the {gcp-short} project ID in which cloud resources will be created.
-<4> Specify the directory containing the files of `CredentialsRequest` manifests to create {gcp-short} service accounts.
-<5> Specify the path to the output directory.
-<6> Specify the path to the `serviceaccount-signer.public` file that you extracted from the cluster.
-<7> Optional: Specify the method for storing OIDC JWK files. Accepted values are `public-bucket` and `pool-jwk-file`. The default value `public-bucket` creates a public GCS bucket to host the OIDC configuration and JWK files. The `pool-jwk-file` value attaches the JWK directly to the workload identity pool provider without creating a public bucket.
+  --name=<name> \
+  --region=<gcp_region> \
+  --project=<gcp_project_id> \
+  --credentials-requests-dir=<path_to_credentials_requests_directory> \
+  --output-dir=<path_to_ccoctl_output_dir> \
+  --public-key-file=<path_to_ccoctl_output_dir>/serviceaccount-signer.public
+  --key-storage-method=<key_storage_method>
+----
+where:
+
+`<name>`:: Specifies the user-defined name for all created {gcp-short} resources used for tracking.
+`<gcp_region>`:: Specifies the {gcp-short} region in which cloud resources will be created.
+`<gcp_project_id>`:: Specifies the {gcp-short} project ID in which cloud resources will be created.
+`<path_to_credentials_requests_directory>`:: Specifies the directory containing the files of `CredentialsRequest` manifests to create {gcp-short} service accounts.
+`<path_to_ccoctl_output_dir>`:: Specifies the path to the output directory.
+`<path_to_ccoctl_output_dir>/serviceaccount-signer.public`:: Specifies the path to the `serviceaccount-signer.public` file that you extracted from the cluster.
+`<key_storage_method>`:: Optional: Specifies the method for storing OIDC JWK files. Accepted values are `public-bucket` and `pool-jwk-file`. The default value `public-bucket` creates a public GCS bucket to host the OIDC configuration and JWK files. The `pool-jwk-file` value attaches the JWK directly to the workload identity pool provider without creating a public bucket.
 +
 [NOTE]
 =====
 If your cluster was previously configured with the `public-bucket` method and you switch to `pool-jwk-file`, the existing GCS bucket is no longer used. You can delete the old `<name>-oidc` bucket from your {gcp-short} project to avoid retaining an unnecessary public resource.
 =====
-====
 +
 .{ibm-cloud-title}
-[%collapsible]
-====
 [source,terminal]
 ----
 $ ccoctl ibmcloud create-service-id \
-  --credentials-requests-dir=<path_to_credential_requests_directory> \// <1>
-  --name=<cluster_name> \// <2>
-  --output-dir=<installation_directory> \// <3>
-  --resource-group-name=<resource_group_name> <4>
-----
-<1> Specify the directory containing the files for the component `CredentialsRequest` objects.
-<2> Specify the name of the {product-title} cluster.
-<3> Optional: Specify the directory in which you want the `ccoctl` utility to create objects. By default, the utility creates objects in the directory in which the commands are run.
-<4> Optional: Specify the name of the resource group used for scoping the access policies.
-====
+  --credentials-requests-dir=<path_to_credential_requests_directory> \
+  --name=<cluster_name> \
+  --output-dir=<installation_directory> \
+  --resource-group-name=<resource_group_name>
+----
+where:
+
+`<path_to_credential_requests_directory>`:: Specifies the directory containing the files for the component `CredentialsRequest` objects.
+`<cluster_name>`:: Specifies the name of the {product-title} cluster.
+`<installation_directory>`:: Optional: Specifies the directory in which you want the `ccoctl` utility to create objects. By default, the utility creates objects in the directory in which the commands are run.
+`<resource_group_name>`:: Optional: Specifies the name of the resource group used for scoping the access policies.
+
 +
 .{azure-first}
-[%collapsible]
-====
 [source,terminal]
 ----
 $ ccoctl azure create-managed-identities \
-  --name <azure_infra_name> \// <1>
-  --output-dir=<path_to_ccoctl_output_dir> \// <2>
-  --region <azure_region> \// <3>
-  --subscription-id <azure_subscription_id> \// <4>
-  --credentials-requests-dir <path_to_directory_for_credentials_requests> \// <5>
-  --issuer-url "${OIDC_ISSUER_URL}" \// <6>
-  --dnszone-resource-group-name <azure_dns_zone_resourcegroup_name> \// <7>
-  --installation-resource-group-name "${AZURE_INSTALL_RG}" \// <8>
-  --preserve-existing-roles <9>
-----
-<1> The value of the `name` parameter is used to create an Azure resource group.
+  --name <azure_infra_name> \
+  --output-dir=<path_to_ccoctl_output_dir> \
+  --region <azure_region> \
+  --subscription-id <azure_subscription_id> \
+  --credentials-requests-dir <path_to_directory_for_credentials_requests> \
+  --issuer-url "${OIDC_ISSUER_URL}" \
+  --dnszone-resource-group-name <azure_dns_zone_resourcegroup_name> \
+  --installation-resource-group-name "${AZURE_INSTALL_RG}"
+  --preserve-existing-roles
+----
+where:
+
+`<azure_infra_name>`:: Specifies the value of the `name` parameter used to create an Azure resource group.
 To use an existing Azure resource group instead of creating a new one, specify the `--oidc-resource-group-name` argument with the existing group name as its value.
-<2> Specify the path to the output directory.
-<3> Specify the region of the existing cluster.
-<4> Specify the subscription ID of the existing cluster.
-<5> Specify the directory containing the files for the component `CredentialsRequest` objects.
-<6> Specify the OIDC issuer URL from the existing cluster.
+`<path_to_ccoctl_output_dir>`:: Specifies the path to the output directory.
+`<azure_region>`:: Specifies the region of the existing cluster.
+`<azure_subscription_id>`:: Specifies the subscription ID of the existing cluster.
+`<path_to_directory_for_credentials_requests>`:: Specifies the directory containing the files for the component `CredentialsRequest` objects.
+`"${OIDC_ISSUER_URL}"`:: Specifies the OIDC issuer URL from the existing cluster.
 You can obtain this value by running the following command:
 +
 [source,terminal]
@@ -142,8 +143,8 @@ $ oc get authentication cluster \
   -o jsonpath \
   --template='{ .spec.serviceAccountIssuer }'
 ----
-<7> Specify the name of the resource group that contains the DNS zone.
-<8> Specify the {azure-short} resource group name.
+`<azure_dns_zone_resourcegroup_name>`:: Specifies the name of the resource group that contains the DNS zone.
+`"${AZURE_INSTALL_RG}"`:: Specifies the {azure-short} resource group name.
 You can obtain this value by running the following command:
 +
 [source,terminal]
@@ -152,23 +153,25 @@ $ oc get infrastructure cluster \
   -o jsonpath \
   --template '{ .status.platformStatus.azure.resourceGroupName }'
 ----
-<9> Optional: Specify this flag to ensure that any custom role assignments you define on managed identities are not removed during {product-title} updates.
-====
+[NOTE]
+=====
+Specifying the flag `ccoctl.azure.create-managed-identities.preserve-existing-roles` ensures that any custom role assignments you define on managed identities are not removed during {product-title} updates. This flag is optional.
+=====
 +
 .Nutanix
-[%collapsible]
-====
 [source,terminal]
 ----
 $ ccoctl nutanix create-shared-secrets \
-  --credentials-requests-dir=<path_to_credentials_requests_directory> \// <1>
-  --output-dir=<ccoctl_output_dir> \// <2>
-  --credentials-source-filepath=<path_to_credentials_file> <3>
+  --credentials-requests-dir=<path_to_credentials_requests_directory> \
+  --output-dir=<ccoctl_output_dir> \
+  --credentials-source-filepath=<path_to_credentials_file>
 ----
-<1> Specify the path to the directory that contains the files for the component `CredentialsRequests` objects.
-<2> Optional: Specify the directory in which you want the `ccoctl` utility to create objects. By default, the utility creates objects in the directory in which the commands are run.
-<3> Optional: Specify the directory that contains the credentials data YAML file. By default, `ccoctl` expects this file to be in `<home_directory>/.nutanix/credentials`.
-====
+where:
+
+`<path_to_credentials_requests_directory>`:: Specifies the path to the directory that contains the files for the component `CredentialsRequests` objects.
+`<ccoctl_output_dir>`:: Optional: Specifies the directory in which you want the `ccoctl` utility to create objects. By default, the utility creates objects in the directory in which the commands are run.
+`<path_to_credentials_file>`:: Optional: Specifies the directory that contains the credentials data YAML file. By default, `ccoctl` expects this file to be in `<home_directory>/.nutanix/credentials`.
+
 +
 For each `CredentialsRequest` object, `ccoctl` creates the required provider resources and a permissions policy as defined in each `CredentialsRequest` object from the {product-title} release image.
 

modules/cco-determine-mode-cli.adoc

@@ -15,7 +15,8 @@ endif::[]
 [id="cco-determine-mode-cli_{context}"]
 = Determining the Cloud Credential Operator mode by using the CLI
 
-You can determine what mode the Cloud Credential Operator (CCO) is configured to use by using the CLI.
+[role="_abstract"]
+To prepare for updates or troubleshooting, use the CLI to determine the credential management mode the Cloud Credential Operator (CCO) uses.
 
 [NOTE]
 ====

modules/cco-determine-mode-gui.adoc

@@ -15,7 +15,8 @@ endif::[]
 [id="cco-determine-mode-gui_{context}"]
 = Determining the Cloud Credential Operator mode by using the web console
 
-You can determine what mode the Cloud Credential Operator (CCO) is configured to use by using the web console.
+[role="_abstract"]
+Use the web console to determine the Cloud Credential Operator (CCO) mode and to verify your cluster's credential management configuration.
 
 [NOTE]
 ====

modules/cco-manual-upgrade-annotation.adoc

@@ -8,7 +8,8 @@
 [id="cco-manual-upgrade-annotation_{context}"]
 = Indicating that the cluster is ready to upgrade
 
-The Cloud Credential Operator (CCO) `Upgradable` status for a cluster with manually maintained credentials is `False` by default.
+[role="_abstract"]
+Add an annotation to indicate that manually maintained credentials are updated and the cluster is ready to upgrade. By default, the Cloud Credential Operator (CCO) `Upgradable` status for a cluster with manually maintained credentials is `False`.
 
 .Prerequisites
 
@@ -39,7 +40,7 @@ $ oc edit cloudcredential cluster
 +
 Where `<version_number>` is the version that you are upgrading to, in the format `x.y.z`. For example, use `4.12.2` for {product-title} 4.12.2.
 +
-It may take several minutes after adding the annotation for the upgradeable status to change.
+It can take several minutes after adding the annotation for the upgradeable status to change.
 
 .Verification