Skip to content

Commit 3ebfbfe

Browse files
EricPonvelleEricPonvelle
committed
OSDOCS-9614: Created documentation to create a ROSA with HCP cluster that uses external auth for OIDC
1 parent bbced86 commit 3ebfbfe

6 files changed

+334
-0
lines changed

‎_topic_maps/_topic_map_rosa.yml

+4
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
---
@@ -615,6 +617,8 @@ Topics:
615617
# File: understanding-identity-provider
616618
- Name: Configuring identity providers
617619
File: sd-configuring-identity-providers
620+
- Name: Configuring identity providers for ROSA with HCP clusters
621+
File: sd-hcp-configuring-identity-providers
618622
# - Name: Configuring identity providers
619623
# Dir: identity_providers
620624
# Topics:

‎authentication/sd-hcp-configuring-identity-providers.adoc

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="sd-hcp-configuring-identity-providers"]
3+
= Configuring identity providers for {hcp-title} clusters
4+
include::_attributes/attributes-openshift-dedicated.adoc[]
5+
:context: sd-hcp-configuring-identity-providers
6+
7+
toc::[]
8+
9+
After your {product-title} cluster is created, you must configure identity providers to determine how users log in to access the cluster.
10+
11+
To use these external authentication providers, you must create a cluster with this feature enabled. For more information, see xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-ext-auth.adoc#rosa-hcp-sts-creating-a-cluster-ext-auth[Creating ROSA with HCP clusters with external authentication].
12+
13+
include::modules/understanding-idp.adoc[leveloffset=+1]
14+
include::modules/identity-provider-parameters.adoc[leveloffset=+2]
15+
include::modules/config-github-idp.adoc[leveloffset=+1]

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

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
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:
17+
+
18+
* If you did not set environmental variables, run the following command:
19+
+
20+
[NOTE]
21+
====
22+
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. To learn more about the default CIDR ranges for {product-title}, see xref:../networking/cidr-range-definitions.adoc#cidr-range-definitions[CIDR range definitions].
23+
====
24+
+
25+
[source,terminal]
26+
----
27+
$ rosa create cluster --cluster-name=<cluster_name> \
28+
--sts --mode=auto --hosted-cp --operator-roles-prefix <operator-role-prefix> \
29+
--oidc-config-id <ID-of-OIDC-configuration> --external-auth-providers-enabled \
30+
--subnet-ids=<public-subnet-id>,<private-subnet-id>
31+
----
32+
+
33+
* 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:
34+
+
35+
[source,terminal]
36+
----
37+
$ rosa create cluster --hosted-cp --subnet-ids=$SUBNET_IDS --oidc-config-id=$OIDC_ID --cluster-name=<cluster_name> --operator-roles-prefix=$OPERATOR_ROLES_PREFIX --external-auth-providers-enabled
38+
----
39+
40+
.Verification
41+
. Verify that your external authentication is enabled in the cluster details by running the following command:
42+
+
43+
[source,terminal]
44+
----
45+
$ rosa describe cluster --cluster=<cluster_name>
46+
----
47+
+
48+
.Example output
49+
[source,terminal,highlight='50']
50+
----
51+
Name: rosa-ext-test
52+
Display Name: rosa-ext-test
53+
ID: <cluster_id>
54+
External ID: <cluster_ext_id>
55+
Control Plane: ROSA Service Hosted
56+
OpenShift Version: 4.15.3
57+
Channel Group: stable
58+
DNS: <dns>
59+
AWS Account: <AWS_id>
60+
AWS Billing Account: <AWS_id>
61+
API URL: <ocm_api>
62+
Console URL:
63+
Region: us-east-1
64+
Availability:
65+
- Control Plane: MultiAZ
66+
- Data Plane: SingleAZ
67+
68+
Nodes:
69+
- Compute (desired): 2
70+
- Compute (current): 0
71+
Network:
72+
- Type: OVNKubernetes
73+
- Service CIDR: <service_cidr>
74+
- Machine CIDR: <machine_cidr>
75+
- Pod CIDR: <pod_cidr>
76+
- Host Prefix: /23
77+
- Subnets: <subnet_ids>
78+
EC2 Metadata Http Tokens: optional
79+
Role (STS) ARN: arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Installer-Role
80+
Support Role ARN: arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Support-Role
81+
Instance IAM Roles:
82+
- Worker: arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Worker-Role
83+
Operator IAM Roles:
84+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-cloud-network-config-controller-clo
85+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-capa-controller-manager
86+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-control-plane-operator
87+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-kms-provider
88+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-kube-controller-manager
89+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-image-registry-installer-cloud-cred
90+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-ingress-operator-cloud-credentials
91+
- arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-cluster-csi-drivers-ebs-cloud-crede
92+
Managed Policies: Yes
93+
State: ready
94+
Private: No
95+
Created: Mar 29 2024 14:25:52 UTC
96+
User Workload Monitoring: Enabled
97+
Details Page: https://<url>
98+
OIDC Endpoint URL: https://<endpoint> (Managed)
99+
Audit Log Forwarding: Disabled
100+
External Authentication: Enabled
101+
----
102+
103+
. Track the progress of the cluster creation by watching the {product-title} installation program logs. To check the logs, run the following command:
104+
+
105+
[source,terminal]
106+
----
107+
$ rosa logs install --cluster=<cluster_name> --watch <1>
108+
----
109+
<1> Optional: To watch for new log messages as the installation progresses, use the `--watch` argument.

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

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="rosa-hcp-sts-creating-a-cluster-external-auth-provider-cli_{context}"]
6+
= Creating an external authentication provider
7+
:source-highlighter: pygments
8+
:pygments-style: emacs
9+
:icons: font
10+
11+
After you have created a {hcp-title} cluster with the enabled option for external authentication providers, you must create a provider using the ROSA CLI.
12+
13+
.Procedure
14+
15+
. Run the following command to create your external authentication provider:
16+
+
17+
[source,terminal]
18+
----
19+
$ rosa create external-aut-provider -c <cluster_name>
20+
----
21+
+
22+
This command starts an interactive CLI process:
23+
+
24+
--
25+
[source,terminal]
26+
----
27+
I: Enabling interactive mode
28+
? Name: <.>
29+
? Issuer audiences: <.>
30+
? The serving url of the token issuer: <.>
31+
? CA file path (optional): <.>
32+
? Claim mapping username: <.>
33+
? Claim mapping groups: <.>
34+
? Claim validation rule (optional): <.>
35+
? Console client id (optional): <.>
36+
----
37+
<.> The name of your external authentication provider. This name should be a lower-case with numbers and dashes.
38+
<.> The issuer audiences field requires you to provide the audience IDs that this authentication provider issues tokens for.
39+
<.> This field uses the issuer's URL that serves the token.
40+
<.> Optional: This field takes the path of a certificate file to use when making requests.
41+
<.> The name of the claim that is used to construct the user names for cluster identity, such as using `email`.
42+
<.> This field specifies how to transform the ID token into a cluster identity, such as using `groups`.
43+
<.> Optional: These are rules that help validate token claims which authenticate your users. This field should be formatted as `<claim:<required_value>`.
44+
<.> Optional: This field is the application or client ID that your app registration uses for the console.
45+
--
46+
47+
.Verification
48+
49+
. View the external authentication configuration on your cluster by running the following commands:
50+
51+
* List the external authentication configuration on a specified cluster with the following command:
52+
+
53+
[source,terminal]
54+
----
55+
$ rosa list external-auth-provider -c <cluster_name>
56+
----
57+
+
58+
.Example output
59+
+
60+
[source,terminal]
61+
----
62+
NAME ISSUER URL
63+
m-entra-id https://login.microsoftonline.com/<group_id>/v2.0
64+
----
65+
66+
* Display the external authentication configuration on a specified cluster by using the following command:
67+
+
68+
[source,terminal]
69+
----
70+
$ rosa describe external-auth-provider -c <cluster_name> --name <name_of_external_authentication>
71+
----
72+
+
73+
.Example output
74+
+
75+
[source,terminal]
76+
----
77+
ID: ms-entra-id
78+
Cluster ID: <cluster_id>
79+
Issuer audiences:
80+
- <audience_id>
81+
Issuer Url: https://login.microsoftonline.com/<group_id>/v2.0
82+
Claim mappings group: groups
83+
Claim mappings username: email
84+
----

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

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="rosa-hcp-sts-creating-a-cluster-external-auth-provider-delete-cli_{context}"]
6+
= Deleting an external authentication provider
7+
:source-highlighter: pygments
8+
:pygments-style: emacs
9+
:icons: font
10+
11+
Delete external authentication providers by using the ROSA CLI.
12+
13+
.Procedure
14+
15+
. Run the following command to display your external authentication provider on your cluster:
16+
+
17+
[source,terminal]
18+
----
19+
$ rosa list external-auth-provider -c <cluster_name>
20+
----
21+
+
22+
.Example output
23+
[source,terminal]
24+
----
25+
NAME ISSUER URL
26+
entra-test https://login.microsoftonline.com/<group_id>/v2.0
27+
----
28+
29+
. Run the following command to delete the external authentication provider:
30+
+
31+
[source,terminal]
32+
----
33+
$ rosa delete external-auth-provider <name_of_provider> -c <cluster_name>
34+
----
35+
+
36+
.Example output
37+
[source,terminal]
38+
----
39+
? Are you sure you want to delete external authentication provider entra-test on cluster rosa-ext-test? Yes
40+
I: Successfully deleted external authentication provider 'entra-test' from cluster 'rosa-ext-test'
41+
----
42+
43+
.Verification
44+
. Run the following command to query for any external authentication providers on your cluster:
45+
+
46+
[source,terminal]
47+
----
48+
$ rosa list external-auth-provider -c <cluster_name>
49+
----
50+
+
51+
.Example output
52+
[source,terminal]
53+
----
54+
E: there are no external authentication providers for this cluster
55+
----

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

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="rosa-hcp-sts-creating-a-cluster-ext-auth"]
3+
= Creating ROSA with HCP clusters with external authentication
4+
include::_attributes/attributes-openshift-dedicated.adoc[]
5+
:context: rosa-hcp-sts-creating-a-cluster-ext-auth
6+
7+
toc::[]
8+
9+
You can create {hcp-title-first} clusters that use an external authentication to issue your access tokens.
10+
11+
[IMPORTANT]
12+
====
13+
Since it is not possible to upgrade or convert existing ROSA clusters to a {hcp} architecture, you must create a new cluster to use {hcp-title} functionality.
14+
====
15+
16+
[NOTE]
17+
====
18+
{hcp-title} clusters only support AWS Security Token Service (STS) authentication.
19+
====
20+
21+
.Further reading
22+
* For a comparison between {hcp-title} and ROSA Classic, see the xref:../rosa_architecture/rosa_architecture_sub/rosa-architecture-models.adoc#rosa-hcp-classic-comparison_rosa-architecture-models[Comparing architecture models] documentation.
23+
* See the AWS documentation for information about link:https://docs.aws.amazon.com/rosa/latest/userguide/getting-started-hcp.html[Getting started with ROSA with HCP using the ROSA CLI in auto mode].
24+
25+
.Additional resources
26+
27+
For a full list of the supported certificates, see the xref:../rosa_architecture/rosa_policy_service_definition/rosa-policy-process-security.adoc#rosa-policy-compliance_rosa-policy-process-security[Compliance] section of "Understanding process and security for Red Hat OpenShift Service on AWS".
28+
29+
[id="next-steps-hcp-ext-auth_{context}"]
30+
.Next steps
31+
32+
* Ensure that you have completed the xref:../rosa_planning/rosa-sts-aws-prereqs.adoc[AWS prerequisites].
33+
34+
[id="rosa-hcp-external-auth-prereqs"]
35+
== {hcp-title} Prerequisites
36+
37+
To create a {hcp-title} cluster, you must have the following items:
38+
39+
* A xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc#rosa-hcp-creating-vpc[configured virtual private cloud (VPC)]
40+
* xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc#rosa-sts-creating-account-wide-sts-roles-and-policies_rosa-hcp-sts-creating-a-cluster-quickly[Account-wide roles]
41+
* An xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc#rosa-sts-byo-oidc_rosa-hcp-sts-creating-a-cluster-quickly[OIDC configuration]
42+
* xref:../rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc#rosa-operator-config_rosa-hcp-sts-creating-a-cluster-quickly[Operator roles]
43+
44+
// Step 1 Prepare HCP cluster with --external-auth-providers-enabled
45+
include::modules/rosa-hcp-sts-creating-a-cluster-ext-auth-cluster-cli.adoc[leveloffset=+1]
46+
//Step 2 Create/list/delete external_provider to HCP cluster that external_auth_config is not enable
47+
include::modules/rosa-hcp-sts-creating-a-cluster-ext-auth-provider-cli.adoc[leveloffset=+1]
48+
//Step 3 delete external_provider to HCP cluster that external_auth_config is not enable
49+
include::modules/rosa-hcp-sts-creating-a-cluster-ext-auth-provider-delete-cli.adoc[leveloffset=+1]
50+
51+
[id="next-steps-2_{context}"]
52+
== Next steps
53+
54+
* xref:../rosa_install_access_delete_clusters/rosa-sts-accessing-cluster.adoc#rosa-sts-accessing-cluster[Accessing a ROSA cluster]
55+
56+
[role="_additional-resources"]
57+
[id="additional-resources_rosa-sts-creating-a-cluster-ext-auth"]
58+
== Additional resources
59+
60+
* For steps to deploy a ROSA cluster using manual mode, see xref:../rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-with-customizations.adoc#rosa-sts-creating-cluster-using-customizations_rosa-sts-creating-a-cluster-with-customizations[Creating a cluster using customizations].
61+
* For more information about the AWS Identity Access Management (IAM) resources required to deploy {product-title} with STS, see xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-about-iam-resources[About IAM resources for clusters that use STS].
62+
* For details about optionally setting an Operator role name prefix, see xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-about-operator-role-prefixes_rosa-sts-about-iam-resources[About custom Operator IAM role prefixes].
63+
* For information about the prerequisites to installing ROSA with STS, see xref:../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-sts-aws-prereqs[AWS prerequisites for ROSA with STS].
64+
* For details about using the `auto` and `manual` modes to create the required STS resources, see xref:../rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-with-customizations.adoc#rosa-understanding-deployment-modes_rosa-sts-creating-a-cluster-with-customizations[Understanding the auto and manual deployment modes].
65+
* For more information about using OpenID Connect (OIDC) identity providers in AWS IAM, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html[Creating OpenID Connect (OIDC) identity providers] in the AWS documentation.
66+
* For more information about troubleshooting ROSA cluster installations, see xref:../support/troubleshooting/rosa-troubleshooting-installations.adoc#rosa-troubleshooting-installations[Troubleshooting installations].
67+
* For steps to contact Red Hat Support for assistance, see xref:../support/getting-support.adoc#getting-support[Getting support for Red Hat OpenShift Service on AWS].

0 commit comments

Comments
 (0)