From 022a69a212cd88975f254d139e77bda59bea2bc1 Mon Sep 17 00:00:00 2001 From: Brendan Daly Date: Tue, 7 Jul 2026 14:52:28 +0100 Subject: [PATCH 1/3] OSDOCS-17075_a: CCO CQA updates --- ...nually-maintained-credentials-upgrade.adoc | 2 +- modules/cco-ccoctl-upgrading.adoc | 178 +++++++++--------- modules/cco-determine-mode-cli.adoc | 3 +- modules/cco-determine-mode-gui.adoc | 3 +- modules/cco-manual-upgrade-annotation.adoc | 5 +- 5 files changed, 100 insertions(+), 91 deletions(-) diff --git a/modules/about-manually-maintained-credentials-upgrade.adoc b/modules/about-manually-maintained-credentials-upgrade.adoc index 1cefb7af37f0..828e6ea9d392 100644 --- a/modules/about-manually-maintained-credentials-upgrade.adoc +++ b/modules/about-manually-maintained-credentials-upgrade.adoc @@ -7,8 +7,8 @@ [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. After updating the cloud provider resources, you must update the `upgradeable-to` annotation for the cluster to indicate that it is ready to update. diff --git a/modules/cco-ccoctl-upgrading.adoc b/modules/cco-ccoctl-upgrading.adoc index 758308326113..0cb12cbc1268 100644 --- a/modules/cco-ccoctl-upgrading.adoc +++ b/modules/cco-ccoctl-upgrading.adoc @@ -1,14 +1,9 @@ -// 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 [role="_abstract"] -Update the cloud provider resources for your {product-title} cluster by using the CCO utility (`ccoctl`). The process for upgrading these resources is similar to creating the resources during installation. +Update the cloud provider resources for your {product-title} cluster by using the CCO utility (`ccoctl`). The process for upgrading these resources is similar to creating the resources during installation [NOTE] ==== @@ -43,97 +38,106 @@ $ 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= \// <2> - --region= \// <3> - --credentials-requests-dir= \// <4> - --output-dir= \// <5> - --public-key-file=/serviceaccount-signer.public \// <6> - --create-private-s3-bucket \// <7> - --permissions-boundary-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= \// + --region= \ + --credentials-requests-dir= \ + --output-dir= \ + --public-key-file= + /serviceaccount-signer.public \ + --create-private-s3-bucket + --permissions-boundary-arn= +---- ++ +where: + +[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. ==== + +``:: Specifies the name used to tag any cloud resources that are created for tracking. +``:: Specifies the AWS region in which cloud resources will be created. +``:: Specifies the directory containing the files for the component `CredentialsRequest` objects. +``:: Specifies the path to the output directory. +`/serviceaccount-signer.public`:: Specifies the path to the `serviceaccount-signer.public` file that you extracted from the cluster. + +[NOTE] +==== +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. +==== + +``:: 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= \// <1> - --region= \// <2> - --project= \// <3> - --credentials-requests-dir= \// <4> - --output-dir= \// <5> - --public-key-file=/serviceaccount-signer.public \// <6> - --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= \ + --region= \ + --project= \ + --credentials-requests-dir= \ + --output-dir= \ + --public-key-file=/serviceaccount-signer.public + --key-storage-method= +---- +where: + +``:: Specifies the user-defined name for all created {gcp-short} resources used for tracking. +``:: Specifies the {gcp-short} region in which cloud resources will be created. +``:: Specifies the {gcp-short} project ID in which cloud resources will be created. +``:: Specifies the directory containing the files of `CredentialsRequest` manifests to create {gcp-short} service accounts. +``:: Specifies the path to the output directory. +`/serviceaccount-signer.public`:: Specifies the path to the `serviceaccount-signer.public` file that you extracted from the cluster. +``:: 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 `-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= \// <1> - --name= \// <2> - --output-dir= \// <3> - --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= \ + --name= \ + --output-dir= \ + --resource-group-name= +---- +where: + +``:: Specifies the directory containing the files for the component `CredentialsRequest` objects. +``:: Specifies the name of the {product-title} cluster. +``:: 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. +``:: 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 \// <1> - --output-dir= \// <2> - --region \// <3> - --subscription-id \// <4> - --credentials-requests-dir \// <5> - --issuer-url "${OIDC_ISSUER_URL}" \// <6> - --dnszone-resource-group-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 \ + --output-dir= \ + --region \ + --subscription-id \ + --credentials-requests-dir \ + --issuer-url "${OIDC_ISSUER_URL}" \ + --dnszone-resource-group-name \ + --installation-resource-group-name "${AZURE_INSTALL_RG}" + --preserve-existing-roles +---- +where: + +``:: 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. +``:: Specifies the path to the output directory. +``:: Specifies the region of the existing cluster. +``:: Specifies the subscription ID of the existing cluster. +``:: 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 +146,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. +``:: 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 +156,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= \// <1> - --output-dir= \// <2> - --credentials-source-filepath= <3> + --credentials-requests-dir= \ + --output-dir= \ + --credentials-source-filepath= ---- -<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 `/.nutanix/credentials`. -==== +where: + +``:: Specifies the path to the directory that contains the files for the component `CredentialsRequests` objects. +``:: 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. +``:: Optional: Specifies the directory that contains the credentials data YAML file. By default, `ccoctl` expects this file to be in `/.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. diff --git a/modules/cco-determine-mode-cli.adoc b/modules/cco-determine-mode-cli.adoc index 05e0164b3512..fd7b5b3eff67 100644 --- a/modules/cco-determine-mode-cli.adoc +++ b/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] ==== diff --git a/modules/cco-determine-mode-gui.adoc b/modules/cco-determine-mode-gui.adoc index 860c60775dd8..943694c382f9 100644 --- a/modules/cco-determine-mode-gui.adoc +++ b/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] ==== diff --git a/modules/cco-manual-upgrade-annotation.adoc b/modules/cco-manual-upgrade-annotation.adoc index cd8b39c6c745..6ef445ad0722 100644 --- a/modules/cco-manual-upgrade-annotation.adoc +++ b/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 `` 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 From 1577d9e90c1c510c5962744aede65df6d976a3e0 Mon Sep 17 00:00:00 2001 From: Brendan Daly Date: Wed, 8 Jul 2026 09:24:15 +0100 Subject: [PATCH 2/3] 1 --- modules/cco-determine-mode-gui.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/cco-determine-mode-gui.adoc b/modules/cco-determine-mode-gui.adoc index 943694c382f9..7bc971b4f1bc 100644 --- a/modules/cco-determine-mode-gui.adoc +++ b/modules/cco-determine-mode-gui.adoc @@ -16,7 +16,7 @@ endif::[] = Determining the Cloud Credential Operator mode 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 +Use the web console to determine the Cloud Credential Operator (CCO) mode and to verify your cluster's credential management configuration. [NOTE] ==== From eaffebaa983e219306eb3631f2c8be5725c1e76a Mon Sep 17 00:00:00 2001 From: Brendan Daly Date: Thu, 9 Jul 2026 07:57:12 +0100 Subject: [PATCH 3/3] 1 --- .../about-manually-maintained-credentials-upgrade.adoc | 1 + modules/cco-ccoctl-upgrading.adoc | 9 +++------ 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/modules/about-manually-maintained-credentials-upgrade.adoc b/modules/about-manually-maintained-credentials-upgrade.adoc index 828e6ea9d392..f0a1a28803ba 100644 --- a/modules/about-manually-maintained-credentials-upgrade.adoc +++ b/modules/about-manually-maintained-credentials-upgrade.adoc @@ -9,6 +9,7 @@ [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. After updating the cloud provider resources, you must update the `upgradeable-to` annotation for the cluster to indicate that it is ready to update. diff --git a/modules/cco-ccoctl-upgrading.adoc b/modules/cco-ccoctl-upgrading.adoc index 0cb12cbc1268..f03a38da8ff8 100644 --- a/modules/cco-ccoctl-upgrading.adoc +++ b/modules/cco-ccoctl-upgrading.adoc @@ -3,7 +3,7 @@ = Updating cloud provider resources with the Cloud Credential Operator utility [role="_abstract"] -Update the cloud provider resources for your {product-title} cluster by using the CCO utility (`ccoctl`). The process for upgrading these resources is similar to creating the resources during installation +Update the cloud provider resources for your {product-title} cluster by using the CCO utility (`ccoctl`). The process for upgrading these resources is similar to creating the resources during installation. [NOTE] ==== @@ -53,11 +53,6 @@ $ ccoctl aws create-all \ + where: -[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. -==== - ``:: Specifies the name used to tag any cloud resources that are created for tracking. ``:: Specifies the AWS region in which cloud resources will be created. ``:: Specifies the directory containing the files for the component `CredentialsRequest` objects. @@ -66,6 +61,8 @@ To create the AWS resources individually, use the "Creating AWS resources indivi [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. ====