Skip to content

Commit 7eafc40

Browse files
EricPonvelleEricPonvelle
committed
OSDOCS-9614: Created documentation to create a ROSA with HCP cluster that uses external auth for OIDC
1 parent 5c65465 commit 7eafc40

9 files changed

+565
-4
lines changed

‎_topic_maps/_topic_map_rosa.yml

+2
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,8 @@ Topics:
227227
File: rosa-hcp-creating-cluster-with-aws-kms-key
228228
- Name: Creating a private cluster on ROSA with HCP
229229
File: rosa-hcp-aws-private-creating-cluster
230+
- Name: Creating ROSA with HCP clusters with external authentication
231+
File: rosa-hcp-sts-creating-a-cluster-ext-auth
230232
- Name: Using the Node Tuning Operator on ROSA with HCP
231233
File: rosa-tuning-config
232234
- Name: Deleting a ROSA with HCP cluster

‎modules/rosa-create-objects.adoc

+78
Original file line numberDiff line numberDiff line change
@@ -273,6 +273,84 @@ Create a cluster with autoscaling enabled on the default worker machine pool.
273273
$ rosa create cluster --cluster-name=mycluster -region=us-east-1 --enable-autoscaling --min-replicas=2 --max-replicas=5
274274
----
275275

276+
[id="rosa-create-external-auth-provider_{context}"]
277+
== create external-auth-provider
278+
279+
Add an external identity provider instead of the OpenShift OAuth2 server.
280+
281+
[IMPORTANT]
282+
====
283+
You can only use external authentication providers on {hcp-title} clusters.
284+
====
285+
286+
.Syntax
287+
[source,terminal]
288+
----
289+
$ rosa create external-auth-provider --cluster=<cluster_name> | <cluster_id> [arguments]
290+
----
291+
292+
.Arguments
293+
[cols="30,70"]
294+
|===
295+
|Option |Definition
296+
297+
|--claim-mapping-groups-claim <string>
298+
|Required. Describes rules on how to transform information from an ID token into a cluster identity.
299+
300+
|--claim-validation-rule <strings>
301+
|Rules that are applied to validate token claims to authenticate users. The input will be in a <claim>:<required_value> format. To have multiple claim validation rules, you can separate the values by ','. For example, <claim>:<required_value>,<claim>:<required_value> format.
302+
303+
|--claim-mapping-username-claim <string>
304+
|The name of the claim that should be used to construct user names for the cluster identity.
305+
306+
a|--cluster <cluster_name>\|<cluster_id>
307+
|Required. The name or ID of the cluster the IDP will be added.
308+
309+
|--console-client-id <string>
310+
|The identifier of the OIDC client from the OIDC provider for the OpenShift web console.
311+
312+
|--console-client-secret <string>
313+
|The secret that is associated with the console application registration.
314+
315+
|--issuer-audiences <strings>
316+
|An array of audiences to check the incoming tokens against. Valid tokens must include at least one of these values in their "aud" claim.
317+
318+
|--issuer-ca-file <string>
319+
|The path to the PEM-encoded certificate file to use when making requests to the server.
320+
321+
|--issuer-url <string>
322+
|The serving URL of the token issuer.
323+
324+
|--name <string>
325+
|A name that is used to refer to the external authentication provider.
326+
|===
327+
328+
.Optional arguments inherited from parent commands
329+
[cols="30,70"]
330+
|===
331+
|Option |Definition
332+
333+
|--help
334+
|Shows help for this command.
335+
336+
|--debug
337+
|Enables debug mode.
338+
339+
|--interactive
340+
|Enables interactive mode.
341+
342+
|--profile
343+
|Specifies an AWS profile string from your credentials file.
344+
|===
345+
346+
.Examples
347+
Add an Entra ID identity provider to a cluster named `mycluster`.
348+
349+
[source,terminal]
350+
----
351+
$ rosa create external-auth-provider --cluster=mycluster --name <provider_name> --issuer-audiences <audience_id> --issuer-url <issuing id> --claim-mapping-username-claim email --claim-mapping-groups-claim groups
352+
----
353+
276354
[id="rosa-create-idp_{context}"]
277355
== create idp
278356

‎modules/rosa-delete-objects.adoc

+49
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,55 @@ Delete a cluster named `mycluster`.
109109
$ rosa delete cluster --cluster=mycluster
110110
----
111111

112+
[id="rosa-delete-external-auth-provider_{context}"]
113+
== delete external-auth-provider
114+
115+
Deletes an external authentication provider from a cluster.
116+
117+
.Syntax
118+
[source,terminal]
119+
----
120+
$ rosa delete external-auth-provider <name_of_external_auth_provider> --cluster=<cluster_name> | <cluster_id> [arguments]
121+
----
122+
123+
.Arguments
124+
[cols="30,70"]
125+
|===
126+
|Option |Definition
127+
128+
|--cluster
129+
|Required. The name or ID string of the cluster the external auth provider will be deleted from.
130+
|===
131+
132+
.Optional arguments inherited from parent commands
133+
[cols="30,70"]
134+
|===
135+
|Option |Definition
136+
137+
|--help
138+
|Shows help for this command.
139+
140+
|--debug
141+
|Enables debug mode.
142+
143+
|--interactive
144+
|Enables interactive mode.
145+
146+
|--profile
147+
|Specifies an AWS profile string from your credentials file.
148+
149+
|--yes
150+
|Automatically answers `yes` to confirm the operation.
151+
|===
152+
153+
.Example
154+
Delete an identity provider named `exauth-1` from a cluster named `mycluster`.
155+
156+
[source,terminal]
157+
----
158+
$ rosa delete external-auth-provider exauth-1 --cluster=mycluster
159+
----
160+
112161
[id="rosa-delete-idp_{context}"]
113162
== delete idp
114163

‎modules/rosa-hcp-sts-creating-a-cluster-cli.adoc

+6-4
Original file line numberDiff line numberDiff line change
@@ -58,16 +58,18 @@ If you specified custom ARN paths when you created the associated account-wide r
5858
+
5959
[source,terminal]
6060
----
61-
$ rosa create cluster --private --cluster-name=<cluster_name> \
62-
--mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
63-
--oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS
61+
$ rosa create cluster --private --cluster-name=<cluster_name> \
62+
--mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
63+
--oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS
6464
----
6565
+
6666
* If you set the environmental variables, create a cluster with a single, initial machine pool, a publicly available API, and a publicly available Ingress by running the following command:
6767
+
6868
[source,terminal]
6969
----
70-
$ rosa create cluster --cluster-name=<cluster_name> --mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX --oidc-config-id=$OIDC_CONFIG --subnet-ids=$SUBNET_IDS
70+
$ rosa create cluster --cluster-name=<cluster_name> --mode=auto \
71+
--hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
72+
--oidc-config-id=$OIDC_CONFIG --subnet-ids=$SUBNET_IDS
7173
----
7274
+
7375
. Check the status of your cluster by running the following command:

‎modules/rosa-hcp-sts-creating-a-cluster-ext-auth-cluster-cli.adoc

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="rosa-hcp-sts-creating-a-cluster-external-auth-cluster-cli_{context}"]
7+
= Creating a {hcp-title} cluster that uses external authentication providers
8+
:source-highlighter: pygments
9+
:pygments-style: emacs
10+
:icons: font
11+
12+
Use the ROSA CLI's `--external-auth-providers-enabled` flag to create your cluster that uses an external authentication service.
13+
14+
.Procedure
15+
16+
. Use one of the following commands to create your ROSA with HCP cluster with the `--external-auth-providers-enabled` flag included:
17+
+
18+
[NOTE]
19+
====
20+
When creating a {hcp-title} cluster, the default machine Classless Inter-Domain Routing (CIDR) is `10.0.0.0/16`. If this does not correspond to the CIDR range for your VPC subnets, add `--machine-cidr <address_block>` to the following commands.
21+
====
22+
+
23+
* If you used the `OIDC_ID`, `SUBNET_IDS`, and `OPERATOR_ROLES_PREFIX` variables to prepare your environment, you can continue to use those variables when creating your cluster. For example, run the following command:
24+
+
25+
[source,terminal]
26+
----
27+
$ rosa create cluster --hosted-cp --subnet-ids=$SUBNET_IDS \
28+
--oidc-config-id=$OIDC_ID --cluster-name=<cluster_name> \
29+
--operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
30+
--external-auth-providers-enabled
31+
----
32+
+
33+
* If you did not set environmental variables, run the following command:
34+
+
35+
[source,terminal]
36+
----
37+
$ rosa create cluster --cluster-name=<cluster_name> --sts --mode=auto \
38+
--hosted-cp --operator-roles-prefix <operator-role-prefix> \
39+
--oidc-config-id <ID-of-OIDC-configuration> \
40+
--external-auth-providers-enabled \
41+
--subnet-ids=<public-subnet-id>,<private-subnet-id>
42+
----
43+
44+
45+
.Verification
46+
. Verify that your external authentication is enabled in the cluster details by running the following command:
47+
+
48+
[source,terminal]
49+
----
50+
$ rosa describe cluster --cluster=<cluster_name>
51+
----
52+
+
53+
.Example output
54+
[source,terminal,highlight='50']
55+
----
56+
Name: rosa-ext-test
57+
Display Name: rosa-ext-test
58+
ID: <cluster_id>
59+
External ID: <cluster_ext_id>
60+
Control Plane: ROSA Service Hosted
61+
OpenShift Version: 4.Y.Z
62+
Channel Group: stable
63+
DNS: <dns>
64+
AWS Account: <AWS_id>
65+
AWS Billing Account: <AWS_id>
66+
API URL: <ocm_api>
67+
Console URL:
68+
Region: us-east-1
69+
Availability:
70+
- Control Plane: MultiAZ
71+
- Data Plane: SingleAZ
72+
73+
Nodes:
74+
- Compute (desired): 2
75+
- Compute (current): 0
76+
Network:
77+
- Type: OVNKubernetes
78+
- Service CIDR: <service_cidr>
79+
- Machine CIDR: <machine_cidr>
80+
- Pod CIDR: <pod_cidr>
81+
- Host Prefix: /23
82+
- Subnets: <subnet_ids>
83+
EC2 Metadata Http Tokens: optional
84+
Role (STS) ARN: arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Installer-Role
85+
Support Role ARN: arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Support-Role
86+
Instance IAM Roles:
87+
- Worker: arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Worker-Role
88+
Operator IAM Roles:
89+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-cloud-network-config-controller-clo
90+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-capa-controller-manager
91+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-control-plane-operator
92+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-kms-provider
93+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-kube-controller-manager
94+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-image-registry-installer-cloud-cred
95+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-ingress-operator-cloud-credentials
96+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-cluster-csi-drivers-ebs-cloud-crede
97+
Managed Policies: Yes
98+
State: ready
99+
Private: No
100+
Created: Jan 01 2030 14:25:52 UTC
101+
User Workload Monitoring: Enabled
102+
Details Page: https://<url>
103+
OIDC Endpoint URL: https://<endpoint> (Managed)
104+
Audit Log Forwarding: Disabled
105+
External Authentication: Enabled
106+
----
107+
108+
. Watch the {hcp-title} installation program logs to track the progress of the cluster creation by running the following command:
109+
+
110+
[source,terminal]
111+
----
112+
$ rosa logs install --cluster=<cluster_name> --watch <1>
113+
----
114+
<1> Optional: To watch for new log messages as the installation progresses, use the `--watch` argument.

0 commit comments

Comments
 (0)