Merge pull request #78406 from jneczypor/OSDOCS-10765

OSDOCS-10765: Re-work "Deploying a cluster" Tutorials for ROSA with HCP

Author: EricPonvelle

_topic_maps/_topic_map_rosa_hcp.yml

@@ -84,7 +84,7 @@ Dir: rosa_learning
 Distros: openshift-rosa-hcp
 Topics:
 - Name: Creating a cluster workshop
-  Dir: cloud-experts-getting-started-deploying
+  Dir: creating_cluster_workshop
   Topics:
   - Name: Deploying a cluster
     File: cloud-experts-getting-started-hcp

rosa_learning/_attributes

@@ -0,0 +1 @@
+../_attributes/

rosa_learning/creating_cluster_workshop/_attributes

@@ -0,0 +1 @@
+../_attributes/

cloud_experts_tutorials/cloud-experts-getting-started/cloud-experts-getting-started-deploying/cloud-experts-getting-started-hcp.adoc renamed to rosa_learning/creating_cluster_workshop/cloud-experts-getting-started-hcp.adoc

@@ -2,6 +2,7 @@
 [id="cloud-experts-getting-started-hcp-guide"]
 = Workshop: Creating a cluster
 include::_attributes/attributes-openshift-dedicated.adoc[]
+include::_attributes/common-attributes.adoc[]
 :context: cloud-experts-getting-started-hcp
 
 toc::[]
@@ -10,27 +11,35 @@ toc::[]
 //Brought into ROSA product docs 2023-11-21
 //Updated for HCP 2024-07-01  
 
-Follow this workshop to deploy a sample {product-title}(ROSA) cluster. You can then use your cluster in other learning workshops.
+Follow this workshop to deploy a sample {product-title} (ROSA) cluster. You can then use your cluster in the next workshops.
 
-== Prerequisites
+.Workshop objectives
 
-Before deploying a ROSA cluster, you must have the following resources:
+* Learn to create your cluster prerequisites:
+** Create a sample virtual private cloud (VPC)
+** Create sample OpenID Connect (OIDC) resources
+* Create sample environment variables
+* Deploy a sample ROSA cluster
 
-* VPC - This is a bring-your-own VPC model, also referred to as BYO-VPC.
-* OIDC - OIDC configuration and an OIDC provider with that specific configuration.
-* ROSA version 1.2.31 or higher
+.Prerequisites
 
-In this tutorial, we will create these resources first. We will also set up some environment variables so that it is easier to run the command to create the {hcp-title} cluster.
+* ROSA version 1.2.31 or later
+* Amazon Web Service (AWS) command line interface (CLI)
+* ROSA CLI (`rosa`)
+
+== Creating your cluster prerequisites
+
+Before deploying a ROSA cluster, you must have both a VPC and OIDC resources. We will create these resources first. ROSA uses the bring your own VPC (BYO-VPC) model.
 
 === Creating a VPC
-. First, ensure that your AWS CLI (`aws`) is configured to use a region where {hcp-title} is available. To find out which regions are supported run the following command:
+. Make sure your AWS CLI (`aws`) is configured to use a region where ROSA is available. See the regions supported by the AWS CLI by running the following command:
 +
 [source,terminal]
 ----
-rosa list regions --hosted-cp
+$ rosa list regions --hosted-cp
 ----
 
-. Create the VPC. For this tutorial, the following link:https://github.com/openshift-cs/rosaworkshop/blob/master/rosa-workshop/rosa/resources/setup-vpc.sh[script] creates the VPC and its required components for you. It uses the region configured for the `aws` CLI.
+. Create the VPC. For this workshop, the following link:https://github.com/openshift-cs/rosaworkshop/blob/master/rosa-workshop/rosa/resources/setup-vpc.sh[script] creates the VPC and its required components. It uses the region configured in your `aws` CLI.
 +
 [source,bash]
 ----
@@ -141,21 +150,23 @@ echo "export PUBLIC_SUBNET_ID=$PUBLIC_SUBNET_ID"
 echo "export PRIVATE_SUBNET_ID=$PRIVATE_SUBNET_ID"
 ----
 +
-For more about VPC requirements, see the xref:../../../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-vpc_rosa-sts-aws-prereqs[VPC documentation].
+[role="_additional-resources"]
+.Additional resources
+* For more about VPC requirements, see the xref:../../../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-vpc_rosa-sts-aws-prereqs[VPC documentation].
 
-. The above script outputs two commands. Set the commands as environment variables to make running the `create cluster` command easier. Copy them from the output and run them as shown:
+. The script outputs commands. Set the commands as environment variables to store the subnet IDs for later use. Copy and run the commands:
 +
 [source,terminal]
 ----
-export PUBLIC_SUBNET_ID=<public subnet id here>
-export PRIVATE_SUBNET_ID=<private subnet id here>
+$ export PUBLIC_SUBNET_ID=$PUBLIC_SUBNET_ID
+$ export PRIVATE_SUBNET_ID=$PRIVATE_SUBNET_ID
 ----
 
-. Confirm that the environment variables are set by running the following command:
+. Confirm your environment variables by running the following command:
 +
 [source,terminal]
 ----
-echo "Public Subnet: $PUBLIC_SUBNET_ID"; echo "Private Subnet: $PRIVATE_SUBNET_ID"
+$ echo "Public Subnet: $PUBLIC_SUBNET_ID"; echo "Private Subnet: $PRIVATE_SUBNET_ID"
 ----
 +
 .Example output
@@ -167,54 +178,57 @@ Private Subnet: subnet-011fe340000000000
 ----
 
 === Creating your OIDC configuration
+In this workshop, we will use the automatic mode when creating the OIDC configuration. We will also store the OIDC ID as an environment variable for later use. The command uses the ROSA CLI to create your cluster's unique OIDC configuration. 
 
-In this tutorial, we will use the automatic mode when creating the OIDC configuration. We will also store the OIDC ID as an environment variable for later use. The command uses the ROSA CLI to create your cluster's unique OIDC configuration. 
-
-* To create the OIDC configuration for this tutorial, run the following command:
+* Create the OIDC configuration by running the following command:
 +
 [source,terminal]
 ----
-export OIDC_ID=$(rosa create oidc-config --mode auto --managed --yes -o json | jq -r '.id')
+$ export OIDC_ID=$(rosa create oidc-config --mode auto --managed --yes -o json | jq -r '.id')
 ----
 
-=== Creating additional environment variables
+== Creating additional environment variables
 
-* Run the following command to set up some environment variables so that it is easier to run the command to create the {hcp-title} cluster:
+* Run the following command to set up environment variables. These variables make it easier to run the command to create a ROSA cluster:
 +
 [source,terminal]
 ----
-export CLUSTER_NAME=<enter cluster name>
-export REGION=<region VPC was created in>
+$ export CLUSTER_NAME=<cluster_name>
+$ export REGION=<VPC_region>
 ----
 +
 [TIP]
 ====
 Run `rosa whoami` to find the VPC region.
 ====
 
-== Creating the cluster
-If this is the _first time_ you are deploying ROSA in this account and you have _not_ yet created the account roles, create the account-wide roles and policies, including the Operator policies. Since ROSA uses AWS Security Token Service (STS), this step creates the AWS IAM roles and policies that are needed for ROSA to interact with your account.
+== Creating a cluster
 
-. Run the following command to create the account-wide roles:
+. *Optional:* Run the following command to create the account-wide roles and policies, including the Operator policies and the AWS IAM roles and policies:
++
+[IMPORTANT]
+====
+Only complete this step if this is the _first time_ you are deploying ROSA in this account and you have _not_ yet created your account roles and policies.
+====
 +
 [source,terminal]
 ----
-rosa create account-roles --mode auto --yes
+$ rosa create account-roles --mode auto --yes
 ----
 
 . Run the following command to create the cluster:
 +
 [source,terminal]
 ----
-rosa create cluster --cluster-name $CLUSTER_NAME \
-    --subnet-ids ${PUBLIC_SUBNET_ID},${PRIVATE_SUBNET_ID} \
-    --hosted-cp \
-    --region $REGION \
-    --oidc-config-id $OIDC_ID \
-    --sts --mode auto --yes
+$ rosa create cluster --cluster-name $CLUSTER_NAME \
+--subnet-ids ${PUBLIC_SUBNET_ID},${PRIVATE_SUBNET_ID} \
+--hosted-cp \
+--region $REGION \
+--oidc-config-id $OIDC_ID \
+--sts --mode auto --yes
 ----
 
-The cluster is ready and completely usable after about 10 minutes. The cluster will have a control plane across three AWS availability zones in your selected region and create two worker nodes in your AWS account.  
+The cluster is ready after about 10 minutes. The cluster will have a control plane across three AWS availability zones in your selected region and create two worker nodes in your AWS account.  
 
 == Checking the installation status
 . Run one of the following commands to check the status of the cluster:
@@ -223,21 +237,21 @@ The cluster is ready and completely usable after about 10 minutes. The cluster w
 +
 [source,terminal]
 ----
-rosa describe cluster --cluster $CLUSTER_NAME
+$ rosa describe cluster --cluster $CLUSTER_NAME
 ----
 +
 * For an abridged view of the cluster status, run:
 +
 [source,terminal]
 ----
-rosa list clusters
+$ rosa list clusters
 ----
 +
 * To watch the log as it progresses, run:
 +
 [source,terminal]
 ----
-rosa logs install --cluster $CLUSTER_NAME --watch
+$ rosa logs install --cluster $CLUSTER_NAME --watch
 ----
 
 . Once the state changes to “ready” your cluster is installed. It might take a few more minutes for the worker nodes to come online.

rosa_learning/creating_cluster_workshop/images

@@ -0,0 +1 @@
+../images/

rosa_learning/creating_cluster_workshop/modules

@@ -0,0 +1 @@
+../modules

rosa_learning/creating_cluster_workshop/snippets

@@ -0,0 +1 @@
+../snippets/

rosa_learning/images

@@ -0,0 +1 @@
+../images/

rosa_learning/modules

@@ -0,0 +1 @@
+../modules

rosa_learning/snippets

@@ -0,0 +1 @@
+../snippets/