Skip to content

[enterprise-4.17] OSDOCS-15947: Add docs for enabling token-based auth on existing aws cluster #100624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: enterprise-4.17
Choose a base branch
from
Open

[enterprise-4.17] OSDOCS-15947: Add docs for enabling token-based auth on existing aws cluster #100624

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 229 additions & 0 deletions modules/enabling-aws-sts-existing-cluster.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,229 @@
// Module included in the following assemblies:
//
// /post_installation_configuration/changing-cloud-credentials-configuration.adoc

:_mod-docs-content-type: PROCEDURE
[id="enabling-aws-sts-existing-cluster_{context}"]
= Enabling {aws-short} {sts-first} on an existing cluster

If you did not configure your {aws-first} {product-title} cluster to use {sts-first} during installation, you can enable this authentication method on an existing cluster.

[IMPORTANT]
====
The process to enable {sts-short} on an existing cluster is disruptive and takes a significant amount of time.
Before proceeding, observe the following considerations:

* Read the following steps and ensure that you understand and accept the time requirement.
The exact time requirement varies depending on the individual cluster, but it is likely to require at least one hour.

* During this process, you must refresh all service accounts and restart all pods on the cluster.
These actions are disruptive to workloads.
To mitigate this impact, you can temporarily halt these services and then redeploy them when the cluster is ready.

* Do not update the cluster until this process is complete.
====

.Prerequisites

* You have installed an {product-title} cluster on {aws-short}.
* You have access to the cluster using an account with `cluster-admin` permissions.
* You have installed the {oc-first}.
* You have extracted and prepared the Cloud Credential Operator utility (`ccoctl`) binary.
* You have access to your AWS account by using the AWS CLI (aws).

.Procedure

. Create an output directory for `ccoctl` generated manifests.
+
[source,terminal]
----
$ mkdir ./output_dir
----

. Create the {aws-short} Identity and Access Management (IAM) OpenID Connect (OIDC) provider.

.. Extract the service account public signing key for the cluster by running the following command:
+
[source,terminal]
----
$ oc get configmap \
--namespace openshift-kube-apiserver bound-sa-token-signing-certs \
--output json | \
jq --raw-output '.data["service-account-001.pub"]' > ./output_dir/serviceaccount-signer.public <1>
----
<1> This procedure uses a file named `serviceaccount-signer.public` as an example.

.. Create the {aws-short} IAM identity provider and S3 bucket by running the following command:
+
[source,terminal]
----
$ ./ccoctl aws create-identity-provider \
--output-dir output_dir \ <1>
--name <name_you_choose> \ <2>
--region us-east-2 \ <3>
--public-key-file output_dir/serviceaccount-signer.public <4>
----
<1> Specify the output directory you created earlier.
<2> Specify a globally unique name. This name functions as a prefix for AWS resources created by this command.
<3> Specify the AWS region of the cluster.
<4> Specify the relative path to the `serviceaccount-signer.public` file you created earlier.

.. Save or note the Amazon Resource Name (ARN) for the IAM identity provider. You can find this information in the final line of the output of the previous command.

. Update the cluster authentication configuration.

.. Extract the OIDC issuer URL and update the authentication configuration of the cluster by running the following commands:
+
[source,terminal]
----
$ OIDC_ISSUER_URL=`awk '/serviceAccountIssuer/ { print $2 }' output_dir/manifests/cluster-authentication-02-config.yaml`
$ oc patch authentication cluster --type=merge -p "{\"spec\":{\"serviceAccountIssuer\":\"${OIDC_ISSUER_URL}\"}}"
----

.. Monitor the configuration update progress by running the following command:
+
[source,terminal]
----
$ oc adm wait-for-stable-cluster
----
+
This process might take 15 minutes or longer.
The following output indicates that the process is complete:
+
[source,text]
----
All clusteroperators are stable
----

. Restart pods to apply the issuer update.

.. Restart all of the pods in the cluster by running the following command:
+
[source,terminal]
----
$ oc adm reboot-machine-config-pool mcp/worker mcp/master
----
+
Restarting a pod updates the `serviceAccountIssuer` field and refreshes the service account public signing key.

.. Monitor the restart and update process by running the following command:
+
[source,terminal]
----
$ oc adm wait-for-node-reboot nodes --all
----
+
This process might take 15 minutes or longer. The following output indicates that the process is complete:
+
[source,text]
----
All nodes rebooted
----

. Update the Cloud Credential Operator `spec.credentialsMode` parameter to `Manual` by running the following command:
+
[source,terminal]
----
$ oc patch cloudcredential cluster \
--type=merge \
--patch '{"spec":{"credentialsMode":"Manual"}}'
----

. Extract `CredentialsRequests` objects.

.. Create a `CLUSTER_VERSION` environment variable by running the following command:
+
[source,terminal]
----
$ CLUSTER_VERSION=$(oc get clusterversion version -o json | jq -r '.status.desired.version')
----

.. Create a `CLUSTER_IMAGE` environment variable by running the following command:
+
[source,terminal]
----
$ CLUSTER_IMAGE=$(oc get clusterversion version -o json | jq -r ".status.history[] | select(.version == \"${CLUSTER_VERSION}\") | .image")
----

.. Extract `CredentialsRequests` objects from the release image by running the following command:
+
[source,terminal]
----
$ oc adm release extract \
--credentials-requests \
--cloud=aws \
--from ${CLUSTER_IMAGE} \
--to output_dir/cred-reqs
----

. Create {aws-short} IAM roles and apply secrets.

.. Create an IAM role for each `CredentialsRequests` object by running the following command:
+
[source,terminal]
----
$ ./ccoctl aws create-iam-roles \
--output-dir ./output_dir/ \ <1>
--name <name_you_choose> \ <2>
--identity-provider-arn <identity_provider_arn> \ <3>
--region us-east-2 \ <4>
--credentials-requests-dir ./output_dir/cred-reqs/ <5>
----
<1> Specify the output directory you created earlier.
<2> Specify a globally unique name. This name functions as a prefix for AWS resources created by this command.
<3> Specify the ARN for the IAM identity provider.
<4> Specify the AWS region of the cluster.
<5> Specify the relative path to the folder where you extracted the `CredentialsRequest` files with the `oc adm release extract` command.

.. Apply the generated secrets by running the following command:
+
[source,terminal]
----
$ find ./output_dir/manifests -iname "openshift*yaml" -print0 | xargs -I {} -0 -t oc replace -f {}
----

. Finish the configuration process by restarting the cluster.

.. Restart all of the pods in the cluster by running the following command:
+
[source,terminal]
----
$ oc adm reboot-machine-config-pool mcp/worker mcp/master
----

.. Monitor the restart and update process by running the following command:
+
[source,terminal]
----
$ oc adm wait-for-node-reboot nodes --all
----
+
This process might take 15 minutes or longer.
The following output indicates that the process is complete:
+
[source,text]
----
All nodes rebooted
----

.. Monitor the configuration update progress by running the following command:
+
[source,terminal]
----
$ oc adm wait-for-stable-cluster
----
+
This process might take 15 minutes or longer.
The following output indicates that the process is complete:
+
[source,text]
----
All clusteroperators are stable
----

. Optional: Remove the {aws-short} root credentials secret by running the following command:
+
[source,terminal]
----
$ oc delete secret -n kube-system aws-creds
----
5 changes: 5 additions & 0 deletions post_installation_configuration/changing-cloud-credentials-configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,15 @@ include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
//Enabling {entra-first} on an existing cluster
include::modules/enabling-entra-workload-id-existing-cluster.adoc[leveloffset=+2]

//Enabling AWS {sts-first} on an existing cluster
include::modules/enabling-aws-sts-existing-cluster.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources
* xref:../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds-azure_cco-short-term-creds[Microsoft Entra Workload ID]
* xref:../installing/installing_azure/ipi/installing-azure-customizations.adoc#installing-azure-with-short-term-creds_installing-azure-customizations[Configuring an Azure cluster to use short-term credentials]
* xref:../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds-aws_cco-short-term-creds[AWS Security Token Service]
* xref:../installing/installing_aws/ipi/installing-aws-customizations.adoc#installing-aws-with-short-term-creds_installing-aws-customizations[Configuring an AWS cluster to use short-term credentials]

//Verifying the credentials configuration
include::modules/cco-ccoctl-install-verifying.adoc[leveloffset=+2]
Expand Down