mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
CCO-84: ccoctl upgrade process
This commit is contained in:
Jeana Routh
committed by
openshift-cherrypick-robot
openshift-cherrypick-robot
parent
a5b5dc7520
commit
fa1eeba4ad
@@ -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]
|
||||
|
||||
96
modules/cco-ccoctl-upgrading.adoc
Normal file
96
modules/cco-ccoctl-upgrading.adoc
Normal file
@@ -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 `_<path_to_ccoctl_output_dir>_` 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=__<path_to_directory_with_list_of_credentials_requests>__/credrequests 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.
|
||||
+
|
||||
.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 __<component_namespace>__
|
||||
----
|
||||
|
||||
. Use the `ccoctl` tool to process all `CredentialsRequest` objects in the `credrequests` directory:
|
||||
+
|
||||
[source,terminal,subs="+quotes"]
|
||||
----
|
||||
$ ccoctl aws create-iam-roles --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
|
||||
----
|
||||
+
|
||||
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.
|
||||
+
|
||||
[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 __<path_to_ccoctl_output_dir>__/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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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]
|
||||
|
||||
|
||||
@@ -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]
|
||||
====
|
||||
|
||||
@@ -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]
|
||||
====
|
||||
|
||||
@@ -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]
|
||||
====
|
||||
|
||||
@@ -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]
|
||||
====
|
||||
|
||||
Reference in New Issue
Block a user