[OSDOCS-4353]: Adds GCP workload ID upgrade procedure

Author: jeana-redhat

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

@@ -117,18 +117,17 @@ 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]
 
-////
-// No Upgrade in 4.10 but this should work exactly the same as AWS STS does.
 [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: sts-mode-upgrading
+:context: wif-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-gcp-workload-identity

authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc

@@ -111,15 +111,10 @@ The release image for the version of {product-title} that you are upgrading to c
 
 :context: sts-mode-upgrading
 
-//Task part 1: Configuring the Cloud Credential Operator utility
 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]
 
-//Task part 3: Run the OCP installer
-//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]
+:context: cco-mode-sts

modules/cco-ccoctl-configuring.adoc

@@ -8,6 +8,9 @@
 ifeval::["{context}" == "cco-mode-sts"]
 :aws-sts:
 endif::[]
+ifeval::["{context}" == "sts-mode-upgrading"]
+:aws-sts:
+endif::[]
 ifeval::["{context}" == "configuring-iam-ibm-cloud"]
 :ibm-cloud:
 endif::[]
@@ -17,6 +20,9 @@ endif::[]
 ifeval::["{context}" == "cco-mode-gcp-workload-identity"]
 :google-cloud-platform:
 endif::[]
+ifeval::["{context}" == "wif-mode-upgrading"]
+:google-cloud-platform:
+endif::[]
 ifeval::["{context}" == "preparing-to-install-on-nutanix"]
 :nutanix:
 endif::[]
@@ -96,11 +102,11 @@ endif::aws-sts[]
 $ RELEASE_IMAGE=$(./openshift-install version | awk '/release image/ {print $3}')
 ----
 
-. Get the CCO container image from the {product-title} release image by running the following command:
+. Obtain the CCO container image from the {product-title} release image by running the following command:
 +
 [source,terminal]
 ----
-$ CCO_IMAGE=$(oc adm release info --image-for='cloud-credential-operator' $RELEASE_IMAGE)
+$ CCO_IMAGE=$(oc adm release info --image-for='cloud-credential-operator' $RELEASE_IMAGE -a ~/.pull-secret)
 ----
 +
 [NOTE]
@@ -157,6 +163,9 @@ Use "ccoctl [command] --help" for more information about a command.
 ifeval::["{context}" == "cco-mode-sts"]
 :!aws-sts:
 endif::[]
+ifeval::["{context}" == "sts-mode-upgrading"]
+:!aws-sts:
+endif::[]
 ifeval::["{context}" == "configuring-iam-ibm-cloud"]
 :!ibm-cloud:
 endif::[]
@@ -166,6 +175,9 @@ endif::[]
 ifeval::["{context}" == "cco-mode-gcp-workload-identity"]
 :!google-cloud-platform:
 endif::[]
+ifeval::["{context}" == "wif-mode-upgrading"]
+:!google-cloud-platform:
+endif::[]
 ifeval::["{context}" == "preparing-to-install-on-nutanix"]
 :!nutanix:
 endif::[]

modules/cco-ccoctl-creating-individually.adoc

@@ -75,7 +75,7 @@ where:
 2021/04/13 11:16:18 Identity Provider created with ARN: arn:aws:iam::<aws_account_id>:oidc-provider/<name>-oidc.s3.<aws_region>.amazonaws.com
 ----
 +
-where `02-openid-configuration` is a discovery document and `03-keys.json` is a JSON web key set file.
+where `openid-configuration` is a discovery document and `keys.json` is a JSON web key set file.
 +
 This command also creates a YAML configuration file in `/<path_to_ccoctl_output_dir>/manifests/cluster-authentication-02-config.yaml`. This file sets the issuer URL field for the service account tokens that the cluster generates, so that the AWS IAM identity provider trusts the tokens.
 

modules/cco-ccoctl-upgrading.adoc

@@ -6,36 +6,27 @@
 ifeval::["{context}" == "sts-mode-upgrading"]
 :aws-sts:
 endif::[]
-ifeval::["{context}" == "cco-mode-gcp-workload-identity"]
+ifeval::["{context}" == "wif-mode-upgrading"]
 :google-cloud-platform:
 endif::[]
 
 :_content-type: PROCEDURE
 [id="cco-ccoctl-upgrading_{context}"]
-ifdef::aws-sts[]
-= Updating AWS resources with the Cloud Credential Operator utility
+= Updating cloud provider resources with the Cloud Credential Operator utility
 
-The process for upgrading an {product-title} cluster configured for manual mode with AWS Secure Token Service (STS) is similar to installing on a cluster for which you create the AWS resources individually.
+The process for upgrading an {product-title} cluster configured for 
+ifdef::aws-sts[manual mode with STS]
+ifdef::google-cloud-platform[manual mode with GCP Workload Identity]
+is similar to creating the cloud provider resources during installation.
 
 [NOTE]
 ====
 By default, `ccoctl` creates objects in the directory in which the commands are run. To create the objects in a different directory, use the `--output-dir` flag. This procedure uses `<path_to_ccoctl_output_dir>` to refer to this directory.
+ifdef::aws-sts[]
 
 Some `ccoctl` commands make AWS API calls to create or modify AWS resources. You can use the `--dry-run` flag to avoid making API calls. Using this flag creates JSON files on the local file system instead. You can review and modify the JSON files and then apply them with the AWS CLI tool using the `--cli-input-json` parameters.
-====
 endif::aws-sts[]
-ifdef::google-cloud-platform[]
-= Updating GCP resources with the Cloud Credential Operator utility
-
-The process for upgrading an {product-title} cluster configured for manual mode with GCP Workload Identity is similar to installing on a cluster for which you create the GCP resources individually.
-
-[NOTE]
 ====
-By default, `ccoctl` creates objects in the directory in which the commands are run. To create the objects in a different directory, use the `--output-dir` flag. This procedure uses `<path_to_ccoctl_output_dir>` to refer to this directory.
-
-Some `ccoctl` commands make GCP API calls to create or modify GCP resources. You can use the `--dry-run` flag to avoid making API calls. Using this flag creates bash scripts with Google Cloud CLI commands on the local file system instead. You can review and modify the bash scripts and then run them to create the required GCP resources.
-====
-endif::google-cloud-platform[]
 
 .Prerequisites
 
@@ -45,12 +36,13 @@ endif::google-cloud-platform[]
 
 .Procedure
 
-. Extract the list of `CredentialsRequest` custom resources (CRs) from the {product-title} release image:
+. Extract the list of `CredentialsRequest` custom resources (CRs) from the {product-title} release image by running the following command:
 +
 [source,terminal]
 ----
 $ oc adm release extract --credentials-requests \
---cloud=aws \
+ifdef::aws-sts[--cloud=aws \]
+ifdef::google-cloud-platform[--cloud=gcp \]
 --to=<path_to_directory_with_list_of_credentials_requests>/credrequests \ <1>
 quay.io/<path_to>/ocp-release:<version>
 ----
@@ -59,6 +51,7 @@ quay.io/<path_to>/ocp-release:<version>
 
 . For each `CredentialsRequest` CR in the release image, ensure that a namespace that matches the text in the `spec.secretRef.namespace` field exists in the cluster. This field is where the generated secrets that hold the credentials configuration are stored.
 +
+ifdef::aws-sts[]
 .Sample AWS `CredentialsRequest` object
 [source,yaml]
 ----
@@ -68,9 +61,6 @@ metadata:
   name: cloud-credential-operator-iam-ro
   namespace: openshift-cloud-credential-operator
 spec:
-  secretRef:
-    name: cloud-credential-operator-iam-ro-creds
-    namespace: openshift-cloud-credential-operator <1>
   providerSpec:
     apiVersion: cloudcredential.openshift.io/v1
     kind: AWSProviderSpec
@@ -81,26 +71,58 @@ spec:
       - iam:GetUserPolicy
       - iam:ListAccessKeys
       resource: "*"
+  secretRef:
+    name: cloud-credential-operator-iam-ro-creds
+    namespace: openshift-cloud-credential-operator <1>
 ----
+endif::aws-sts[]
+ifdef::google-cloud-platform[]
+.Sample GCP `CredentialsRequest` object
+[source,yaml]
+----
+apiVersion: cloudcredential.openshift.io/v1
+kind: CredentialsRequest
+metadata:
+  annotations:
+    exclude.release.openshift.io/internal-openshift-hosted: "true"
+    include.release.openshift.io/self-managed-high-availability: "true"
+  name: cloud-credential-operator-gcp-ro-creds
+  namespace: openshift-cloud-credential-operator
+spec:
+  providerSpec:
+    apiVersion: cloudcredential.openshift.io/v1
+    kind: GCPProviderSpec
+    predefinedRoles:
+    - roles/iam.securityReviewer
+    - roles/iam.roleViewer
+    skipServiceCheck: true
+  secretRef:
+    name: cloud-credential-operator-gcp-ro-creds
+    namespace: openshift-cloud-credential-operator <1>
+  serviceAccountNames:
+  - cloud-credential-operator
+----
+endif::google-cloud-platform[]
 +
 <1> This field indicates the namespace which needs to exist to hold the generated secret.
 
-. For any `CredentialsRequest` CR for which the cluster does not already have a namespace with the name specified in `spec.secretRef.namespace`, create the namespace:
+. For any `CredentialsRequest` CR for which the cluster does not already have a namespace with the name specified in `spec.secretRef.namespace`, create the namespace by running the following command:
 +
-[source,terminal,subs="+quotes"]
+[source,terminal]
 ----
 $ oc create namespace <component_namespace>
 ----
 
-. Use the `ccoctl` tool to process all `CredentialsRequest` objects in the `credrequests` directory:
+. Use the `ccoctl` tool to process all `CredentialsRequest` objects in the `credrequests` directory by running the following command:
 +
-[source,terminal,subs="+quotes"]
+ifdef::aws-sts[]
+[source,terminal]
 ----
 $ ccoctl aws create-iam-roles \
---name <name> \
+--name=<name> \
 --region=<aws_region> \
 --credentials-requests-dir=<path_to_directory_with_list_of_credentials_requests>/credrequests \
---identity-provider-arn arn:aws:iam::<aws_account_id>:oidc-provider/<name>-oidc.s3.<aws_region>.amazonaws.com
+--identity-provider-arn=arn:aws:iam::<aws_account_id>:oidc-provider/<cluster_name>-oidc.s3.<aws_region>.amazonaws.com
 ----
 +
 where:
@@ -109,6 +131,7 @@ where:
 ** `<name>` is the name used to tag any cloud resources that are created for tracking. For upgrades, use the same value that was used for the initial installation.
 ** `<aws_account_id>` is the AWS account ID.
 ** `<aws_region>` is the AWS region in which cloud resources will be created.
+** `<aws_account_id>`, `<cluster_name>`, and `<aws_region>` are standard elements of the Amazon Resource Name (ARN) for your cluster, provided here to illustrate the format of an ARN. You can obtain the ARN for your cluster's identity provider from the *Identity Providers* menu in the link:https://console.aws.amazon.com/iam/[AWS IAM console]. 
 --
 +
 [NOTE]
@@ -117,10 +140,38 @@ For AWS environments that use alternative IAM API endpoints, such as GovCloud, y
 
 If your cluster uses Technology Preview features that are enabled by the `TechPreviewNoUpgrade` feature set, you must include the `--enable-tech-preview` parameter.
 ====
+endif::aws-sts[]
+ifdef::google-cloud-platform[]
+[source,terminal]
+----
+$ ccoctl gcp create-service-accounts \
+--credentials-requests-dir=<path_to_directory_with_list_of_credentials_requests>/credrequests \
+--name=<name> \
+--project=<gcp_project_id> \
+--workload-identity-pool=<name> \
+--workload-identity-provider=<name>
+----
++
+where:
++
+--
+** `<path_to_directory_with_list_of_credentials_requests>/credrequests` is the directory containing the files of `CredentialsRequest` manifests to create GCP service accounts.
+** `<name>` is the user-defined name for all created GCP resources used for tracking.
+** `<gcp_project_id>` is the GCP project ID in which cloud resources will be created.
+--
++
+[NOTE]
+====
+If your cluster uses Technology Preview features that are enabled by the `TechPreviewNoUpgrade` feature set, you must include the `--enable-tech-preview` parameter.
+====
+endif::google-cloud-platform[]
 +
-For each `CredentialsRequest` object, `ccoctl` creates an IAM role with a trust policy that is tied to the specified OIDC identity provider, and a permissions policy as defined in each `CredentialsRequest` object from the {product-title} release image.
+For each `CredentialsRequest` object, `ccoctl` creates 
+ifdef::aws-sts[an IAM role with a trust policy that is tied to the specified OIDC identity provider,]
+ifdef::google-cloud-platform[a service account]
+and a permissions policy as defined in each `CredentialsRequest` object from the {product-title} release image.
 
-. Apply the secrets to your cluster:
+. Apply the secrets to your cluster by running the following command:
 +
 [source,terminal]
 ----
@@ -129,11 +180,22 @@ $ ls <path_to_ccoctl_output_dir>/manifests/*-credentials.yaml | xargs -I{} oc ap
 
 .Verification
 
-You can verify that the IAM roles are created by querying AWS. For more information, refer to AWS documentation on listing IAM roles.
+You can verify that the 
+ifdef::aws-sts[IAM roles]
+ifdef::google-cloud-platform[service accounts]
+are created by querying 
+ifdef::aws-sts[AWS.]
+ifdef::google-cloud-platform[GCP.]
+For more information, refer to 
+ifdef::aws-sts[AWS]
+ifdef::google-cloud-platform[GCP]
+documentation on listing 
+ifdef::aws-sts[IAM roles.]
+ifdef::google-cloud-platform[service accounts.]
 
 ifeval::["{context}" == "sts-mode-upgrading"]
 :!aws-sts:
 endif::[]
-ifeval::["{context}" == "cco-mode-gcp-workload-identity"]
+ifeval::["{context}" == "wif-mode-upgrading"]
 :!google-cloud-platform:
 endif::[]