Skip to content

Commit c83c9f9

Browse files
sslocketopenshift-cherrypick-robot
sslocket
authored and
openshift-cherrypick-robot
committed
OSDOCS-15947: Add docs for enabling token-based auth on existing aws cluster
1 parent 3dbaa98 commit c83c9f9

File tree

2 files changed

+234
-0
lines changed

2 files changed

+234
-0
lines changed

‎modules/enabling-aws-sts-existing-cluster.adoc‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
// Module included in the following assemblies:
2+
//
3+
// /post_installation_configuration/changing-cloud-credentials-configuration.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="enabling-aws-sts-existing-cluster_{context}"]
7+
= Enabling {aws-short} {sts-first} on an existing cluster
8+
9+
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.
10+
11+
[IMPORTANT]
12+
====
13+
The process to enable {sts-short} on an existing cluster is disruptive and takes a significant amount of time.
14+
Before proceeding, observe the following considerations:
15+
16+
* Read the following steps and ensure that you understand and accept the time requirement.
17+
The exact time requirement varies depending on the individual cluster, but it is likely to require at least one hour.
18+
19+
* During this process, you must refresh all service accounts and restart all pods on the cluster.
20+
These actions are disruptive to workloads.
21+
To mitigate this impact, you can temporarily halt these services and then redeploy them when the cluster is ready.
22+
23+
* Do not update the cluster until this process is complete.
24+
====
25+
26+
.Prerequisites
27+
28+
* You have installed an {product-title} cluster on {aws-short}.
29+
* You have access to the cluster using an account with `cluster-admin` permissions.
30+
* You have installed the {oc-first}.
31+
* You have extracted and prepared the Cloud Credential Operator utility (`ccoctl`) binary.
32+
* You have access to your AWS account by using the AWS CLI (aws).
33+
34+
.Procedure
35+
36+
. Create an output directory for `ccoctl` generated manifests.
37+
+
38+
[source,terminal]
39+
----
40+
$ mkdir ./output_dir
41+
----
42+
43+
. Create the {aws-short} Identity and Access Management (IAM) OpenID Connect (OIDC) provider.
44+
45+
.. Extract the service account public signing key for the cluster by running the following command:
46+
+
47+
[source,terminal]
48+
----
49+
$ oc get configmap \
50+
--namespace openshift-kube-apiserver bound-sa-token-signing-certs \
51+
--output json | \
52+
jq --raw-output '.data["service-account-001.pub"]' > ./output_dir/serviceaccount-signer.public <1>
53+
----
54+
<1> This procedure uses a file named `serviceaccount-signer.public` as an example.
55+
56+
.. Create the {aws-short} IAM identity provider and S3 bucket by running the following command:
57+
+
58+
[source,terminal]
59+
----
60+
$ ./ccoctl aws create-identity-provider \
61+
--output-dir output_dir \ <1>
62+
--name <name_you_choose> \ <2>
63+
--region us-east-2 \ <3>
64+
--public-key-file output_dir/serviceaccount-signer.public <4>
65+
----
66+
<1> Specify the output directory you created earlier.
67+
<2> Specify a globally unique name. This name functions as a prefix for AWS resources created by this command.
68+
<3> Specify the AWS region of the cluster.
69+
<4> Specify the relative path to the `serviceaccount-signer.public` file you created earlier.
70+
71+
.. 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.
72+
73+
. Update the cluster authentication configuration.
74+
75+
.. Extract the OIDC issuer URL and update the authentication configuration of the cluster by running the following commands:
76+
+
77+
[source,terminal]
78+
----
79+
$ OIDC_ISSUER_URL=`awk '/serviceAccountIssuer/ { print $2 }' output_dir/manifests/cluster-authentication-02-config.yaml`
80+
$ oc patch authentication cluster --type=merge -p "{\"spec\":{\"serviceAccountIssuer\":\"${OIDC_ISSUER_URL}\"}}"
81+
----
82+
83+
.. Monitor the configuration update progress by running the following command:
84+
+
85+
[source,terminal]
86+
----
87+
$ oc adm wait-for-stable-cluster
88+
----
89+
+
90+
This process might take 15 minutes or longer.
91+
The following output indicates that the process is complete:
92+
+
93+
[source,text]
94+
----
95+
All clusteroperators are stable
96+
----
97+
98+
. Restart pods to apply the issuer update.
99+
100+
.. Restart all of the pods in the cluster by running the following command:
101+
+
102+
[source,terminal]
103+
----
104+
$ oc adm reboot-machine-config-pool mcp/worker mcp/master
105+
----
106+
+
107+
Restarting a pod updates the `serviceAccountIssuer` field and refreshes the service account public signing key.
108+
109+
.. Monitor the restart and update process by running the following command:
110+
+
111+
[source,terminal]
112+
----
113+
$ oc adm wait-for-node-reboot nodes --all
114+
----
115+
+
116+
This process might take 15 minutes or longer. The following output indicates that the process is complete:
117+
+
118+
[source,text]
119+
----
120+
All nodes rebooted
121+
----
122+
123+
. Update the Cloud Credential Operator `spec.credentialsMode` parameter to `Manual` by running the following command:
124+
+
125+
[source,terminal]
126+
----
127+
$ oc patch cloudcredential cluster \
128+
--type=merge \
129+
--patch '{"spec":{"credentialsMode":"Manual"}}'
130+
----
131+
132+
. Extract `CredentialsRequests` objects.
133+
134+
.. Create a `CLUSTER_VERSION` environment variable by running the following command:
135+
+
136+
[source,terminal]
137+
----
138+
$ CLUSTER_VERSION=$(oc get clusterversion version -o json | jq -r '.status.desired.version')
139+
----
140+
141+
.. Create a `CLUSTER_IMAGE` environment variable by running the following command:
142+
+
143+
[source,terminal]
144+
----
145+
$ CLUSTER_IMAGE=$(oc get clusterversion version -o json | jq -r ".status.history[] | select(.version == \"${CLUSTER_VERSION}\") | .image")
146+
----
147+
148+
.. Extract `CredentialsRequests` objects from the release image by running the following command:
149+
+
150+
[source,terminal]
151+
----
152+
$ oc adm release extract \
153+
--credentials-requests \
154+
--cloud=aws \
155+
--from ${CLUSTER_IMAGE} \
156+
--to output_dir/cred-reqs
157+
----
158+
159+
. Create {aws-short} IAM roles and apply secrets.
160+
161+
.. Create an IAM role for each `CredentialsRequests` object by running the following command:
162+
+
163+
[source,terminal]
164+
----
165+
$ ./ccoctl aws create-iam-roles \
166+
--output-dir ./output_dir/ \ <1>
167+
--name <name_you_choose> \ <2>
168+
--identity-provider-arn <identity_provider_arn> \ <3>
169+
--region us-east-2 \ <4>
170+
--credentials-requests-dir ./output_dir/cred-reqs/ <5>
171+
----
172+
<1> Specify the output directory you created earlier.
173+
<2> Specify a globally unique name. This name functions as a prefix for AWS resources created by this command.
174+
<3> Specify the ARN for the IAM identity provider.
175+
<4> Specify the AWS region of the cluster.
176+
<5> Specify the relative path to the folder where you extracted the `CredentialsRequest` files with the `oc adm release extract` command.
177+
178+
.. Apply the generated secrets by running the following command:
179+
+
180+
[source,terminal]
181+
----
182+
$ find ./output_dir/manifests -iname "openshift*yaml" -print0 | xargs -I {} -0 -t oc replace -f {}
183+
----
184+
185+
. Finish the configuration process by restarting the cluster.
186+
187+
.. Restart all of the pods in the cluster by running the following command:
188+
+
189+
[source,terminal]
190+
----
191+
$ oc adm reboot-machine-config-pool mcp/worker mcp/master
192+
----
193+
194+
.. Monitor the restart and update process by running the following command:
195+
+
196+
[source,terminal]
197+
----
198+
$ oc adm wait-for-node-reboot nodes --all
199+
----
200+
+
201+
This process might take 15 minutes or longer.
202+
The following output indicates that the process is complete:
203+
+
204+
[source,text]
205+
----
206+
All nodes rebooted
207+
----
208+
209+
.. Monitor the configuration update progress by running the following command:
210+
+
211+
[source,terminal]
212+
----
213+
$ oc adm wait-for-stable-cluster
214+
----
215+
+
216+
This process might take 15 minutes or longer.
217+
The following output indicates that the process is complete:
218+
+
219+
[source,text]
220+
----
221+
All clusteroperators are stable
222+
----
223+
224+
. Optional: Remove the {aws-short} root credentials secret by running the following command:
225+
+
226+
[source,terminal]
227+
----
228+
$ oc delete secret -n kube-system aws-creds
229+
----

‎post_installation_configuration/changing-cloud-credentials-configuration.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,10 +81,15 @@ include::modules/cco-ccoctl-configuring.adoc[leveloffset=+2]
8181
//Enabling {entra-first} on an existing cluster
8282
include::modules/enabling-entra-workload-id-existing-cluster.adoc[leveloffset=+2]
8383

84+
//Enabling AWS {sts-first} on an existing cluster
85+
include::modules/enabling-aws-sts-existing-cluster.adoc[leveloffset=+2]
86+
8487
[role="_additional-resources"]
8588
.Additional resources
8689
* xref:../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds-azure_cco-short-term-creds[Microsoft Entra Workload ID]
8790
* 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]
91+
* xref:../authentication/managing_cloud_provider_credentials/cco-short-term-creds.adoc#cco-short-term-creds-aws_cco-short-term-creds[AWS Security Token Service]
92+
* 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]
8893

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

0 commit comments

Comments
 (0)