OSDOCS-9614: Created documentation to create a ROSA with HCP cluster that uses external auth for OIDC

Author: EricPonvelle

_attributes/attributes-openshift-dedicated.adoc

@@ -5,6 +5,7 @@
 :experimental:
 :imagesdir: images
 :OCP: OpenShift Container Platform
+:OCP-short: OpenShift
 :ocp-version: 4.14
 :op-system-first: Red Hat Enterprise Linux CoreOS (RHCOS)
 :cluster-manager-first: Red Hat OpenShift Cluster Manager
@@ -21,6 +22,9 @@
 :rhq-short: Red Hat Quay
 :SMProductName: Red Hat OpenShift Service Mesh
 :pipelines-title: Red Hat OpenShift Pipelines
+:sts-first: Security Token Service (STS)
+:sts-full: Security Token Service
+:sts-short: STS
 //logging
 :logging-title: logging for Red Hat OpenShift
 :logging-title-uc: Logging for Red Hat OpenShift
@@ -47,4 +51,3 @@
 :hcp-title: ROSA with HCP
 :hcp-title-first: {product-title} (ROSA) with {hcp} (HCP)
 //ROSA CLI variables
-:word: Testing this variable let's go www.google.com

_topic_maps/_topic_map_rosa.yml

@@ -227,6 +227,8 @@ Topics:
   File: rosa-hcp-creating-cluster-with-aws-kms-key
 - Name: Creating a private cluster on ROSA with HCP
   File: rosa-hcp-aws-private-creating-cluster
+- Name: Creating ROSA with HCP clusters with external authentication
+  File: rosa-hcp-sts-creating-a-cluster-ext-auth
 - Name: Using the Node Tuning Operator on ROSA with HCP
   File: rosa-tuning-config
 - Name: Deleting a ROSA with HCP cluster

modules/rosa-create-objects.adoc

@@ -273,6 +273,84 @@ Create a cluster with autoscaling enabled on the default worker machine pool.
 $ rosa create cluster --cluster-name=mycluster -region=us-east-1 --enable-autoscaling --min-replicas=2 --max-replicas=5
 ----
 
+[id="rosa-create-external-auth-provider_{context}"]
+== create external-auth-provider
+
+Add an external identity provider instead of the {OCP-short} OAuth2 server.
+
+[IMPORTANT]
+====
+You can only use external authentication providers on {hcp-title} clusters.
+====
+
+.Syntax
+[source,terminal]
+----
+$ rosa create external-auth-provider --cluster=<cluster_name> | <cluster_id> [arguments]
+----
+
+.Arguments
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--claim-mapping-groups-claim <string>     
+|Required. Describes rules on how to transform information from an ID token into a cluster identity.
+
+|--claim-validation-rule <strings>
+|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`.
+
+|--claim-mapping-username-claim <string>
+|The name of the claim that should be used to construct user names for the cluster identity.
+
+a|--cluster <cluster_name>\|<cluster_id>
+|Required. The name or ID of the cluster to which the IDP will be added.
+
+|--console-client-id <string>
+|The identifier of the OIDC client from the OIDC provider for the {cluster-manager-url} web console.
+
+|--console-client-secret <string>          
+|The secret that is associated with the console application registration.
+
+|--issuer-audiences <strings>
+|An array of audiences to check the incoming tokens against. Valid tokens must include at least one of these values in their audience claim.
+
+|--issuer-ca-file <string>
+|The path to the PEM-encoded certificate file to use when making requests to the server.
+
+|--issuer-url <string>
+|The serving URL of the token issuer.
+
+|--name <string>
+|A name that is used to refer to the external authentication provider.
+|===
+
+.Optional arguments inherited from parent commands
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--help
+|Shows help for this command.
+
+|--debug
+|Enables debug mode.
+
+|--interactive
+|Enables interactive mode.
+
+|--profile
+|Specifies an AWS profile string from your credentials file.
+|===
+
+.Examples
+Add a Microsoft Entra ID identity provider to a cluster named `mycluster`.
+
+[source,terminal]
+----
+$ 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
+----
+
 [id="rosa-create-idp_{context}"]
 == create idp
 

modules/rosa-delete-objects.adoc

@@ -109,6 +109,55 @@ Delete a cluster named `mycluster`.
 $ rosa delete cluster --cluster=mycluster
 ----
 
+[id="rosa-delete-external-auth-provider_{context}"]
+== delete external-auth-provider
+
+Deletes an external authentication provider from a cluster.
+
+.Syntax
+[source,terminal]
+----
+$ rosa delete external-auth-provider <name_of_external_auth_provider> --cluster=<cluster_name> | <cluster_id> [arguments]
+----
+
+.Arguments
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--cluster
+|Required. The name or ID string of the cluster the external auth provider will be deleted from.
+|===
+
+.Optional arguments inherited from parent commands
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--help
+|Shows help for this command.
+
+|--debug
+|Enables debug mode.
+
+|--interactive
+|Enables interactive mode.
+
+|--profile
+|Specifies an AWS profile string from your credentials file.
+
+|--yes
+|Automatically answers `yes` to confirm the operation.
+|===
+
+.Example
+Delete an identity provider named `exauth-1` from a cluster named `mycluster`.
+
+[source,terminal]
+----
+$ rosa delete external-auth-provider exauth-1 --cluster=mycluster
+----
+
 [id="rosa-delete-idp_{context}"]
 == delete idp
 

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

@@ -58,16 +58,18 @@ If you specified custom ARN paths when you created the associated account-wide r
 +
 [source,terminal]
 ----
-$ rosa create cluster --private --cluster-name=<cluster_name> \ 
-  --mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \ 
-  --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS
+$ rosa create cluster --private --cluster-name=<cluster_name> \
+    --mode=auto --hosted-cp --operator-roles-prefix=$OPERATOR_ROLES_PREFIX \
+    --oidc-config-id=$OIDC_ID --subnet-ids=$SUBNET_IDS
 ----
 +
 * 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:
 +
 [source,terminal]
 ----
-$ 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
+$ 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
 ----
 +
 . Check the status of your cluster by running the following command:

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

@@ -0,0 +1,111 @@
+// Module included in the following assemblies:
+//
+// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="rosa-hcp-sts-creating-a-cluster-external-auth-cluster-cli_{context}"]
+= Creating a {hcp-title} cluster that uses external authentication providers
+:source-highlighter: pygments
+:pygments-style: emacs
+:icons: font
+ 
+Use the `--external-auth-providers-enabled` flag in the ROSA CLI to create a cluster that uses an external authentication service.
+
+[NOTE]
+====
+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.
+====
+
+.Procedure
+
+* 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:
++
+[source,terminal]
+----
+$ 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
+----
+
+* If you did not set environmental variables, run the following command:
++
+[source,terminal]
+----
+$ rosa create cluster --cluster-name=<cluster_name> --sts --mode=auto \
+    --hosted-cp --operator-roles-prefix <operator-role-prefix> \
+    --oidc-config-id <ID-of-OIDC-configuration> \
+    --external-auth-providers-enabled \
+    --subnet-ids=<public-subnet-id>,<private-subnet-id>
+----
+
+.Verification
+. Verify that your external authentication is enabled <.> in the cluster details by running the following command:
++
+[source,terminal]
+----
+$ rosa describe cluster --cluster=<cluster_name>
+----
++
+.Example output
+[source,terminal,highlight='50']
+----
+Name:                       rosa-ext-test
+Display Name:               rosa-ext-test
+ID:                         <cluster_id>
+External ID:                <cluster_ext_id>
+Control Plane:              ROSA Service Hosted
+OpenShift Version:          4.Y.Z
+Channel Group:              stable
+DNS:                        <dns>
+AWS Account:                <AWS_id>
+AWS Billing Account:        <AWS_id>
+API URL:                    <ocm_api>
+Console URL:
+Region:                     us-east-1
+Availability:
+ - Control Plane:           MultiAZ
+ - Data Plane:              SingleAZ
+
+Nodes:
+ - Compute (desired):       2
+ - Compute (current):       0
+Network:
+ - Type:                    OVNKubernetes
+ - Service CIDR:            <service_cidr>
+ - Machine CIDR:            <machine_cidr>
+ - Pod CIDR:                <pod_cidr>
+ - Host Prefix:             /23
+ - Subnets:                 <subnet_ids>
+EC2 Metadata Http Tokens:   optional
+Role (STS) ARN:             arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Installer-Role
+Support Role ARN:           arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Support-Role
+Instance IAM Roles:
+ - Worker:                  arn:aws:iam::<AWS_id>:role/<account_roles_prefix>-HCP-ROSA-Worker-Role
+Operator IAM Roles:
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-cloud-network-config-controller-clo
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-capa-controller-manager
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-control-plane-operator
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-kms-provider
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-kube-system-kube-controller-manager
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-image-registry-installer-cloud-cred
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-ingress-operator-cloud-credentials
+ - arn:aws:iam::<AWS_id>:role/<operator_roles_prefix>-openshift-cluster-csi-drivers-ebs-cloud-crede
+Managed Policies:           Yes
+State:                      ready
+Private:                    No
+Created:                    Jan 01 2030 14:25:52 UTC
+User Workload Monitoring:   Enabled
+Details Page:               https://<url>
+OIDC Endpoint URL:          https://<endpoint> (Managed)
+Audit Log Forwarding:       Disabled
+External Authentication:    Enabled <.>
+----
+
+. Watch the {hcp-title} installation program logs to track the progress of the cluster creation by running the following command:
++
+[source,terminal]
+----
+$ rosa logs install --cluster=<cluster_name> --watch <1>
+----
+<1> Optional: To watch for new log messages as the installation progresses, use the `--watch` argument.