Merge pull request #58031 from EricPonvelle/OSDOCS-5660_ROSA-HCP-Context

EricPonvelle · web-flow · commit 344c148fd085 · 2023-04-18T16:48:55.000-04:00
[OSDOCS-5660] Added additional context to ROSA HCP documentation
diff --git a/_attributes/attributes-openshift-dedicated.adoc b/_attributes/attributes-openshift-dedicated.adoc
@@ -29,3 +29,4 @@
 :openshift-local-productname: Red Hat OpenShift Local
 :openshift-dev-spaces-productname: Red Hat OpenShift Dev Spaces
 :hcp: hosted control planes
+:hcp-first: Hosted control planes
diff --git a/modules/rosa-hcp-byo-oidc-options.adoc b/modules/rosa-hcp-byo-oidc-options.adoc
@@ -0,0 +1,68 @@
+// Module included in the following assemblies:
+//
+// * rosa_install_access_delete_clusters/rosa-sts-creating-a-cluster-quickly.adoc
+// * rosa_getting_started/quickstart.adoc
+
+:_content-type: CONCEPT
+[id="rosa-hcp-byo-oidc-options_{context}"]
+= Parameter options for creating your own OpenID Connect configuration
+
+The following options may be added to the `rosa create oidc-config` command. All of these parameters are optional. Running the `rosa create oidc-config` command without parameters creates an unmanaged OIDC configuration.
+
+[NOTE]
+====
+You are required to register the unmanaged OIDC configuration by posting a request to `/oidc_configs` through OCM. You receive an ID in the response. Use this ID to create a cluster.
+====
+
+[discrete]
+[id="rosa-oidc-raw-files_{context}"]
+== raw-files
+
+Allows you to provide raw files for the private RSA key. This key is named `rosa-private-key-oidc-<random_label_of_length_4>.key`. You also receive a discovery document, named `discovery-document-oidc-<random_label_of_length_4>.json`, and a JSON Web Key Set, named `jwks-oidc-<random_label_of_length_4>.json`.
+
+You use these files to set up the endpoint. This endpoint responds to `/.well-known/openid-configuration` with the discovery document and on `keys.json` with the JSON Web Key Set. The private key is to be stored in Amazon Web Services (AWS) Secrets Manager Service (SMS) as plaintext.
+
+.Example
+[source,terminal]
+----
+$ rosa create oidc-config --raw-files
+----
+
+[discrete]
+[id="rosa-oidc-mode_{context}"]
+== mode
+
+Allows you to specify the mode to create your OIDC configuration. With the `manual` option, you receive AWS commands that setup the OIDC configuration within an S3 bucket. This option stores the private key in the Secrets Manager. With the `manual` option, the OIDC Endpoint URL is the URL for the S3 bucket. You must retrieve the Secrets Manager ARN to register the OIDC configuration with OCM.
+
+Using the `auto` option, like with manual mode, you receive the same OIDC configuration with AWS resources. One change is that ROSA calls AWS, so you do not need to do anything else. The OIDC Endpoint URL is the URL for the S3 bucket. The CLI retrieves the Secrets Manager ARN, registers the OIDC configuration with OCM, and reports a second ROSA command the user can run to continue with creation of STS cluster.
+
+.Example
+[source,terminal]
+----
+$ rosa create oidc-config --mode=<auto|manual>
+----
+
+[discrete]
+[id="rosa-oidc-managed_{context}"]
+== managed
+
+Creates an OIDC configuration that is hosted under Red Hat's AWS account. This command creates a private key that responds directly with an OIDC Config ID for you to use when creating the STS cluster.
+
+.Example
+[source,terminal]
+----
+$ rosa create oidc-config --managed
+----
+
+.Sample output
+[source,terminal]
+----
+W: For a managed OIDC Config only auto mode is supported. However, you may choose the provider creation mode
+? OIDC Provider creation mode: auto
+I: Setting up managed OIDC configuration
+I: Please run the following command to create a cluster with this oidc config
+rosa create cluster --sts --oidc-config-id 233jnu62i9aphpucsj9kueqlkr1vcgra
+I: Creating OIDC provider using 'arn:aws:iam::242819244:user/userName'
+? Create the OIDC provider? Yes
+I: Created OIDC provider with ARN 'arn:aws:iam::242819244:oidc-provider/dvbwgdztaeq9o.cloudfront.net/233jnu62i9aphpucsj9kueqlkr1vcgra'
+----
diff --git a/modules/rosa-hcp-byo-oidc.adoc b/modules/rosa-hcp-byo-oidc.adoc
@@ -4,9 +4,16 @@
 
 :_content-type: PROCEDURE
 [id="rosa-hcp-byo-oidc_{context}"]
-= Configuring your own OpenID Connect provider
+= Generating your own OpenID Connect configuration
 
-You can use your own OpenID Connect (OIDC) provider with {hcp} for {product-title} (ROSA).
+You can create your own OpenID Connect (OIDC) configuration before you create your cluster by using the `rosa create oidc-config --mode=auto` command. This command produces an OIDC configuration that is hosted under Red Hat's AWS account. The `rosa` CLI provides some additional options for creating your OIDC configuration.
+
+You can generate managed or unmanaged OIDC configurations. Customer-hosted, or unmanaged, OIDC configurations are stored within your AWS account with the configurations also being flagged for use with {cluster-manager-first}. This process also provides you with a private key to have access to and take ownership of the configurations. Red-Hat hosted, or managed, OIDC configurations are stored within Red Hat's AWS account. This process provides you with private keys for accessing the configuration. 
+
+[NOTE]
+====
+When using the `--managed` parameter, you can only create a new managed OIDC configuration if there are no unused configurations; all existing OIDC configurations must be attached to a cluster. If you delete all of your clusters with attached managed OIDC configurations, you cannot create a new configuration until the unused one is reused or deleted.
+====
 
 .Prerequisites
 
@@ -19,7 +26,7 @@ You can use your own OpenID Connect (OIDC) provider with {hcp} for {product-titl
 +
 [source,terminal]
 ----
-$ rosa create oidc-config --mode auto
+$ rosa create oidc-config --mode=auto
 ----
 +
 This command returns the following information.
@@ -28,11 +35,34 @@ This command returns the following information.
 +
 [source,terminal]
 ----
-I: This command will create a S3 bucket populating it with documents to be compliant with OIDC protocol. It will also create a Secret in Secrets Manager containing the private key.
-I: Please run command below to create a cluster with this oidc config:
-rosa create cluster --sts \
- --oidc-endpoint-url https://oidc-l8c0.s3.us-east-1.amazonaws.com \
- --oidc-private-key-secret-arn arn:aws:secretsmanager:us-east-1:269733383066:secret:rosa-private-key-oidc-l8c0-4vdMVv
+I: This command will create a S3 bucket populating it with documents to be compliant with OIDC protocol. It will also create a Secret in Secrets Manager containing the private key
+I: Using arn:aws:iam::242819244:role/ManagedOpenShift-Installer-Role for the Installer role
+? Prefix for OIDC (optional): 
+I: Setting up unmanaged OIDC configuration 'oidc-r7u1'
+I: Please run the following command to create a cluster with this oidc config
+rosa create cluster --sts --oidc-config-id 233hvnrjoqu14jltk6lhbhf2tj11f8un
+I: Creating OIDC provider using 'arn:aws:iam::242819244:user/userName'
+? Create the OIDC provider? Yes
+I: Created OIDC provider with ARN 'arn:aws:iam::242819244:oidc-provider/oidc-r7u1.s3.us-east-1.amazonaws.com'
+----
+
+When creating your cluster, you must supply the OIDC config ID. The CLI output provides this value for `--mode auto`, otherwise you must to determine these values based on `aws` CLI output for `--mode manual`.
+
+.Verification
+
+. You can list the possible OIDC configurations available for your clusters that are associated with your user organization. Run the following command:
++ 
+[source,terminal]
+----
+$ rosa list oidc-config
+----
++
+.Sample output
++
+[source,terminal]
 ----
+ID                                MANAGED  ISSUER URL                                                             SECRET ARN
+2330dbs0n8m3chkkr25gkkcd8pnj3lk2  true     https://dvbwgdztaeq9o.cloudfront.net/2330dbs0n8m3chkkr25gkkcd8pnj3lk2  
+233hvnrjoqu14jltk6lhbhf2tj11f8un  false    https://oidc-r7u1.s3.us-east-1.amazonaws.com                           aws:secretsmanager:us-east-1:242819244:secret:rosa-private-key-oidc-r7u1-tM3MDN
 
-When creating your cluster, you must supply the OIDC endpoint URL and secret manager secret ARN. The CLI output provides both values for `--mode auto`, otherwise you must to determine these values based on `aws` CLI output for `--mode manual`.
+----
diff --git a/modules/rosa-hcp-classic-comparison.adoc b/modules/rosa-hcp-classic-comparison.adoc
@@ -0,0 +1,75 @@
+// Module included in the following assemblies:
+//
+// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc 
+
+:_content-type: CONCEPT
+[id="rosa-hcp-classic-comparison_{context}"]
+= Comparing ROSA Classic and hosted control planes for ROSA
+
+{hcp-first} for {product-title} (ROSA) offers a different way to create a managed ROSA cluster. {hcp-first} for ROSA offers a reduced-cost solution with focuses on reliability and efficiency. With a focus on efficiency, you can quickly create a new cluster and deploy applications in minutes. 
+
+{hcp-first} for ROSA requires only a minimum two nodes, making it ideal for smaller projects, while still being able to scale to support larger projects and enterprises.
+
+.ROSA architectures comparison table
+
+[cols="3a,8a,8a",options="header"]
+|===
+| {nbsp} +
+| Hosted Control Plane 
+| Classic
+
+| *What are each of the installation paths?*
+| This installation path deploys control plane components, such as etcd, API server, and oauth, that are hosted separately on AWS in a Red Hat-owned and managed account. 
+| This installation path deploys the control plane components side by side with infrastructure and worker nodes that are hosted together in the customer’s same AWS account.
+
+| *Provisioning Time*
+| Approximately 10 minutes 
+| Approximately 40 minutes 
+
+| *Architecture*
+|
+    * Underlying control plane infrastructure is fully managed and directly unavailable to end customers except through dedicated and explicitly exposed endpoints
+|
+    * Customer is responsible for hosting control plane and AWS infrastructure, while still being _managed_ by Red Hat
+    * All-in-one {product-title} infrastructure architecture
+    
+| *Footprint*
+| 1 cluster requires a minimum of 2 nodes
+| 1 cluster requires minimum of 7 nodes
+
+| *Deployment* 
+| 
+    * Deploy using ROSA CLI or web UI
+    * Customers provision "Hosted Clusters" that deploy the control plane components into Red Hat's AWS account
+    * Customers provision "Machine Pools" that deploy worker nodes into the customer's AWS account
+|
+    * Deploy using ROSA CLI or web UI
+    * Full cluster provisioning occurs in customer's AWS account
+
+| *Upgrades*
+| Selectively upgrade control plane and machine pools separately
+| Entire cluster is upgraded at one time
+
+| *Regional Availability* 
+| 
+//This list is for GA; conceal until ready.
+//    * us-east-1
+    * us-east-2
+//    * us-west2
+    * eu-west-1
+//    * eu-central-1
+//    * ap-southeast-2
+| Available for purchase in all countries where AWS is commercially available 
+
+| *Compliance* 
+| 
+    * Compliance certifications planned for after GA
+    * FIPS compliance not yet available
+| 
+    * ISO 27001, 17, 18
+    * SOC 2 Type 2
+    * SOC 3
+    * PCI-DSS
+    * HIPAA 
+
+|===
diff --git a/modules/rosa-hcp-sts-creating-a-cluster-cli.adoc b/modules/rosa-hcp-sts-creating-a-cluster-cli.adoc
@@ -36,7 +36,7 @@ To successfully install ROSA clusters, use the latest version of the ROSA CLI (`
 +
 [NOTE]
 ====
-If you are using your own OIDC provider, you must include the endpoint URL and ARN arguments, such as `--oidc-endpoint-url <oidc_endpoint_url> --oidc-private-key-secret-arn <oidc_private_key_secret_arn>`.
+If you are using your own OIDC provider, you must include the OIDC config ID, such as `--oidc-config-id <oidc_config_id>`.
 ====
 
 ** Create a cluster with a single, initial machine pool, publicly available API, and publicly available Ingress by running the following command:
diff --git a/modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc b/modules/rosa-sts-overview-of-the-default-cluster-specifications.adoc
@@ -38,7 +38,9 @@ endif::rosa-standalone[]
 
 |Cluster settings
 |* Default cluster version: Latest
+ifndef::rosa-hcp[]
 * Default AWS region for installations using the {cluster-manager-first} {hybrid-console-second}: us-east-1 (US East, North Virginia)
+endif::rosa-hcp[]
 * Default AWS region for installations using the `rosa` CLI: Defined by your `aws` CLI configuration
 * Availability: Single zone for the data plane
 * Monitoring for user-defined projects: Enabled
diff --git a/rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc b/rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
@@ -11,13 +11,22 @@ toc::[]
 If you are looking for a quickstart guide for ROSA, see xref:../rosa_getting_started/rosa-quickstart-guide-ui.adoc#rosa-quickstart-guide-ui[{product-title} quickstart guide].
 ====
 
+{hcp-first} for {product-title} (ROSA) offers a more efficient and reliable architecture for creating ROSA clusters. With {hcp} for ROSA, each cluster has a dedicated control plane that is isolated in a Red Hat account. 
+
+[IMPORTANT]
+====
+Since it is not possible to "upgrade" to a {hcp} architecture, you must create a new cluster to benefit from the {hcp} for {product-title} functionality.
+====
+
 Create {hcp} for a {product-title} (ROSA) cluster quickly by using the default options and automatic AWS Identity and Access Management (IAM) resource creation. You can deploy your cluster by using the ROSA CLI (`rosa`).
 
 [NOTE]
 ====
 All {hcp} for ROSA clusters require AWS Security Token Service (STS) to be enabled.
 ====
 
+include::modules/rosa-hcp-classic-comparison.adoc[leveloffset=+2]
+
 The procedures in this document use the `auto` mode in the ROSA CLI (`rosa`) to immediately create the required IAM resources using the current AWS account. The required resources include the account-wide IAM roles and policies, cluster-specific Operator roles and policies, and OpenID Connect (OIDC) identity provider.
 
 Alternatively, you can use `manual` mode, which outputs the `aws` commands needed to create the IAM resources instead of deploying them automatically. For steps to deploy a {hcp} for ROSA cluster by using `manual` mode or with customizations, 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].
@@ -55,8 +64,17 @@ include::modules/rosa-hcp-vpc-manual.adoc[leveloffset=+2]
 * link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html[Get Started with Amazon VPC]
 * link:https://developer.hashicorp.com/terraform[HashiCorp Terraform documentation]
 
-include::modules/rosa-hcp-byo-oidc.adoc[leveloffset=+1]
-//include::modules/rosa-sts-creating-a-cluster-using-defaults-ocm.adoc[leveloffset=+2]
+[id="rosa-hcp-byo-odic-overview_{context}"]
+== Creating an OpenID Connect Configuration
+
+When using a Red Hat-hosted cluster, you can create a managed or unmanaged OpenID Connect (OIDC) configuration that is generated by the CLI. With a managed OIDC configuration, it is stored within Red Hat's AWS account. A generated unmanaged OIDC configuration is stored in your AWS account. The configuration is registered to be used with OCM. This generated unmanaged OIDC configuration provides the private key for you to access. This process does not provide a private key for users to access.
+
+[discrete]
+include::modules/rosa-hcp-byo-oidc.adoc[leveloffset=+2]
+
+[discrete]
+include::modules/rosa-hcp-byo-oidc-options.adoc[leveloffset=+2]
+
 include::modules/rosa-hcp-sts-creating-a-cluster-cli.adoc[leveloffset=+1]
 
 [id="next-steps-2_{context}"]
diff --git a/snippets/rosa-hcp-rn.adoc b/snippets/rosa-hcp-rn.adoc
@@ -0,0 +1,6 @@
+// Text snippet included in the following modules:
+//
+// * rosa_release_notes/rosa-release-notes.adoc
+
+:_content-type: SNIPPET
+* With the latest version of {product-title}, {product-title} allows you to create a {hcp} for ROSA cluster. This functionality offers a lower-cost, reliable ROSA option for small-scale usage. For more information, see link:https://docs.openshift.com/rosa-hcp/rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.html[Creating hosted control planes for ROSA cluster using the default options].

Original file line number	Diff line number	Diff line change
@@ -36,7 +36,7 @@ To successfully install ROSA clusters, use the latest version of the ROSA CLI (`
`36`	`36`	`+`
`37`	`37`	`[NOTE]`
`38`	`38`	`====`
`39`		-If you are using your own OIDC provider, you must include the endpoint URL and ARN arguments, such as `--oidc-endpoint-url <oidc_endpoint_url> --oidc-private-key-secret-arn <oidc_private_key_secret_arn>`.
	`39`	+If you are using your own OIDC provider, you must include the OIDC config ID, such as `--oidc-config-id <oidc_config_id>`.
`40`	`40`	`====`
`41`	`41`
`42`	`42`	`** Create a cluster with a single, initial machine pool, publicly available API, and publicly available Ingress by running the following command:`