diff --git a/authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc b/authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc index 9da7883612..a520d8c2d0 100644 --- a/authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc +++ b/authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc @@ -92,3 +92,23 @@ 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. + +: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] diff --git a/modules/cco-ccoctl-upgrading.adoc b/modules/cco-ccoctl-upgrading.adoc new file mode 100644 index 0000000000..ed25b89436 --- /dev/null +++ b/modules/cco-ccoctl-upgrading.adoc @@ -0,0 +1,96 @@ +// Module included in the following assemblies: +// +// * authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc + +[id="cco-ccoctl-upgrading_{context}"] += Updating AWS 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. + +[NOTE] +==== +By default, `ccoctl` creates objects in the directory in which the commands are run. To specify a directory, use the `--output-dir` flag. This procedure uses `__` to refer to this location. + +Some `ccoctl` commands make AWS API calls to create or modify AWS resources. To place JSON files on the local file system instead, use the `--dry-run` flag. These JSON files can be reviewed or modified and then applied with the AWS CLI tool using the `--cli-input-json` parameters. +==== + +.Prerequisites + +* Obtain the {product-title} release image for the version that you are upgrading to. + +* Extract and prepare the `ccoctl` binary from the release image. + +.Procedure + +. Extract the list of `CredentialsRequest` custom resources (CRs) from the {product-title} release image: ++ +[source,terminal,subs="+quotes"] +---- +$ oc adm release extract --credentials-requests --cloud=aws --to=____/credrequests quay.io/____/ocp-release:____ +---- + +. 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. ++ +.Sample AWS `CredentialsRequest` object +[source,yaml] +---- +apiVersion: cloudcredential.openshift.io/v1 +kind: CredentialsRequest +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 + statementEntries: + - effect: Allow + action: + - iam:GetUser + - iam:GetUserPolicy + - iam:ListAccessKeys + resource: "*" +---- ++ +<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: ++ +[source,terminal,subs="+quotes"] +---- +$ oc create namespace ____ +---- + +. Use the `ccoctl` tool to process all `CredentialsRequest` objects in the `credrequests` directory: ++ +[source,terminal,subs="+quotes"] +---- +$ ccoctl aws create-iam-roles --name ____ --region=____ --credentials-requests-dir=____/credrequests --identity-provider-arn arn:aws:iam::____:oidc-provider/____-oidc.s3.____.amazonaws.com +---- ++ +where: ++ +** __ 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. +** __ is the AWS account ID. +** __ is the AWS region in which cloud resources will be created. ++ +[NOTE] +==== +For AWS environments that use alternative IAM API endpoints, such as GovCloud, you must also specify your region with the `--region` parameter. +==== ++ +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. + +. Apply the secrets to your cluster: ++ +[source,terminal,subs="+quotes"] +---- +$ ls ____/manifests/*-credentials.yaml | xargs -I{} oc apply -f {} +---- + +.Verification + +You can verify that the IAM roles are created by querying AWS. For more information, refer to AWS documentation on listing IAM roles. diff --git a/modules/manually-maintained-credentials-upgrade.adoc b/modules/manually-maintained-credentials-upgrade.adoc index 41e780e881..0e88e0458d 100644 --- a/modules/manually-maintained-credentials-upgrade.adoc +++ b/modules/manually-maintained-credentials-upgrade.adoc @@ -4,14 +4,14 @@ // * installing/installing_azure/manually-creating-iam-azure.adoc // * installing/installing_gcp/manually-creating-iam-gcp.adoc // * authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc +// * authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc [id="manually-maintained-credentials-upgrade_{context}"] = Upgrading clusters with manually maintained credentials The Cloud Credential Operator (CCO) `Upgradable` status for a cluster with manually maintained credentials is `False` by default. -//to-do: update "from 4.7 to 4.8" to "from 4.8 to 4.9" when 4.9 is released -* For minor releases, for example, from 4.7 to 4.8, this status prevents you from upgrading until you have addressed any updated permissions and annotated the `CloudCredential` resource to indicate that the permissions are updated as needed for the next version. This annotation changes the `Upgradable` status to `True`. +* For minor releases, for example, from 4.8 to 4.9, this status prevents you from upgrading until you have addressed any updated permissions and annotated the `CloudCredential` resource to indicate that the permissions are updated as needed for the next version. This annotation changes the `Upgradable` status to `True`. * For z-stream releases, for example, from 4.8.9 to 4.8.10, no permissions are added or changed, so the upgrade is not blocked. diff --git a/updating/updating-cluster-between-minor.adoc b/updating/updating-cluster-between-minor.adoc index 6043dfc305..96fc0bc8a2 100644 --- a/updating/updating-cluster-between-minor.adoc +++ b/updating/updating-cluster-between-minor.adoc @@ -20,6 +20,7 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis * Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information. * Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. * If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. +* If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being upgraded to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[_Upgrading an OpenShift Container Platform cluster configured for manual mode with STS_]. [IMPORTANT] ==== @@ -43,4 +44,3 @@ include::modules/update-using-custom-machine-config-pools-canary.adoc[leveloffse If you want to use the canary rollout update process, see xref:../updating/update-using-custom-machine-config-pools.adoc#update-using-custom-machine-config-pools[Performing a canary rollout update]. include::modules/update-upgrading-web.adoc[leveloffset=+1] - diff --git a/updating/updating-cluster-cli.adoc b/updating/updating-cluster-cli.adoc index 26ea56472f..61212dcd3c 100644 --- a/updating/updating-cluster-cli.adoc +++ b/updating/updating-cluster-cli.adoc @@ -15,6 +15,7 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis * Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information. * Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. * If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. +* If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being upgraded to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[_Upgrading an OpenShift Container Platform cluster configured for manual mode with STS_]. [IMPORTANT] ==== diff --git a/updating/updating-cluster-rhel-compute.adoc b/updating/updating-cluster-rhel-compute.adoc index 722f5b47ed..f434e2dc38 100644 --- a/updating/updating-cluster-rhel-compute.adoc +++ b/updating/updating-cluster-rhel-compute.adoc @@ -15,6 +15,7 @@ those machines. See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. * Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. * If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. +* If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being upgraded to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[_Upgrading an OpenShift Container Platform cluster configured for manual mode with STS_]. [IMPORTANT] ==== diff --git a/updating/updating-cluster.adoc b/updating/updating-cluster.adoc index 4229e5a368..f06e1cba67 100644 --- a/updating/updating-cluster.adoc +++ b/updating/updating-cluster.adoc @@ -14,6 +14,7 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis * Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. * Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. * If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. +* If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being upgraded to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[_Upgrading an OpenShift Container Platform cluster configured for manual mode with STS_]. [IMPORTANT] ==== diff --git a/updating/updating-restricted-network-cluster.adoc b/updating/updating-restricted-network-cluster.adoc index e4fc5e007c..b677f3221e 100644 --- a/updating/updating-restricted-network-cluster.adoc +++ b/updating/updating-restricted-network-cluster.adoc @@ -21,6 +21,8 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis * Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. * Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. * If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. +//STS is not currently supported in a restricted network environment, but the following bullet can be uncommented when that changes. +//* If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being upgraded to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[_Upgrading an OpenShift Container Platform cluster configured for manual mode with STS_]. [IMPORTANT] ====