Merge pull request #67837 from jneczypor/OSDOCS-8370

OSDOCS-8370: Rosa Getting Started Setup Content Migration

Author: bmcelvee

_topic_maps/_topic_map_rosa.yml

@@ -112,6 +112,12 @@ Topics:
   File: cloud-experts-dynamic-certificate-custom-domain
 - Name: Assigning consistent egress IP for external traffic
   File: cloud-experts-consistent-egress-ip
+- Name: Getting started with ROSA
+  Dir: cloud_experts_getting_started
+  Distros: openshift-rosa
+  Topics:
+  - Name: Setup
+    File: cloud-experts-getting-started-setup
 ---
 Name: Getting started
 Dir: rosa_getting_started

cloud_experts_tutorials/cloud_experts_getting_started/_attributes

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

cloud_experts_tutorials/cloud_experts_getting_started/cloud-experts-getting-started-setup.adoc

@@ -0,0 +1,232 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cloud-experts-getting-started-setup"]
+= Tutorial: Setup
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: cloud-experts-getting-started-setup
+
+toc::[]
+
+//rosaworkshop.io content metadata
+//Brought into ROSA product docs 2023-11-13
+
+There are currently two supported credential methods when creating a {product-title} (ROSA) cluster. One method uses an IAM user with the `AdministratorAccess` policy. The second and *recommended* method uses Amazon Web Services (AWS) Security Token Service (STS). 
+//To be added when the ROSA with STS Explained tutorial is published:
+//For more information, see the xref../cloud_experts_tutorials/cloud_experts_rosa_with_sts_explained.adoc#id[ROSA with STS Explained] tutorial. This workshop uses the STS method.
+
+== Prerequisites
+
+Review the prerequisites listed in the xref:../../rosa_planning/rosa-cloud-expert-prereq-checklist.adoc#rosa-cloud-expert-prereq-checklist[Prerequisites for ROSA with STS] checklist.
+
+You will need the following information from your AWS account:
+
+* AWS IAM user
+* AWS access key ID
+* AWS secret access key
+
+== Setting up a Red Hat account
+. If you do not have a Red Hat account, create one on the link:https://console.redhat.com/[Red Hat console].
+. Accept the required terms and conditions.
+. Then check your email for a verification link.
+
+== Installing the AWS CLI
+* Install the link:https://aws.amazon.com/cli/[AWS CLI] for your operating system.
+
+== Enabling ROSA
+
+[NOTE]
+====
+Only complete this step if you have *not* enabled ROSA in your AWS account.
+====
+
+. Visit the link:https://console.aws.amazon.com/rosa[AWS console] to enable your account to use ROSA.
+. Click the orange *Enable OpenShift* button.
++
+image::cloud-experts-getting-started-setup-enable.png[]
+
+. After about a minute, a green *service enabled* bar should appear.
++
+image::cloud-experts-getting-started-setup-enabled.png[]
+
+== Installing the ROSA CLI
+. Install the link:https://console.redhat.com/openshift/downloads[ROSA CLI] for your operating system.
+. Download and extract the relevant file for your operating system by using the following command:
++
+[source,terminal]
+----
+tar -xvf rosa-linux.tar.gz
+----
+. Save the file to a location within your `PATH` by using the following command:
++
+[source,terminal]
+----
+sudo mv rosa /usr/local/bin/rosa
+----
+. Run `rosa version` to verify a successful installation.
+
+== Installing the OpenShift CLI
+There are a few ways to install the OpenShift CLI (`oc`):
+
+* *Option 1: Using the ROSA CLI:*
+.. Run `rosa download oc`.
+.. Once downloaded, unzip the file and move the executables into a directory in your `PATH`.
+* *Option 2: Using the Openshift documentation:*
+.. Follow the directions on the xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#installing-openshift-cli[documentation page]
+* *Option 3: Using your OpenShift cluster:*
+.. If you already have an OpenShift cluster, you can access the CLI tools page by clicking the *Question mark*, then *Command Line Tools*.
++
+image::cloud_experts_getting_started_setup_cli_tools.png[]
+
+.. Then, download the relevant tool for your operating system.
+
+=== Using `oc` instead of `kubectl`
+While `kubectl` can be used with an OpenShift cluster, `oc` is specific to OpenShift. It includes the standard set of features from `kubectl` as well as additional support for OpenShift functionality. For more information, see xref:../../cli_reference/openshift_cli/usage-oc-kubectl.adoc#usage-oc-kubectl[Usage of oc and kubectl commands].
+
+== Configuring the AWS CLI
+To configure the AWS CLI, follow these steps:
+
+. Enter `aws configure` in the terminal.
+. Enter your AWS access key ID and press enter.
+. Enter your AWS secret access key and press enter.
+. Enter the default region in which you want to deploy.
+. Enter the desired output format, specifying either `table` or `json`.
+
+.Example output
+[source, terminal]
+----
+$ aws configure
+AWS Access Key ID: AKIA0000000000000000
+AWS Secret Access Key: NGvmP0000000000000000000000000
+Default region name: us-east-1
+Default output format: table
+----
+
+== Verifying the configuration
+Verify that the configuration is correct by following these steps:
+
+. Run the following command to query the AWS API:
++
+[source,terminal]
+----      
+aws sts get-caller-identity
+----
+. You should see a table or JSON file. Verify that the account information is correct.
++
+.Example output
++
+[source, terminal]
+----
+$ aws sts get-caller-identity
+------------------------------------------------------------------------------
+|                                GetCallerIdentity                           |
++--------------+----------------------------------------+--------------------+
+|    Account   |                   Arn                  |        UserId      |
++--------------+----------------------------------------+--------------------+
+|  000000000000|  arn:aws:iam::00000000000:user/myuser  |  AIDA00000000000000|
++--------------+----------------------------------------+--------------------+
+----
+
+== Ensuring the ELB service role exists
+[TIP]
+====
+Make sure that the service role for the ELB already exists, otherwise cluster deployment could fail.
+====
+
+* Run the following command to check for the ELB service role and create it if it is missing:
++
+[source,terminal]
+----
+aws iam get-role --role-name "AWSServiceRoleForElasticLoadBalancing" || aws iam create-service-linked-role --aws-service-name "elasticloadbalancing.amazonaws.com"
+----
+
+=== Fixing ELB service role errors
+
+. The following error during cluster creation means that an ELB service role does not exist:
++
+.Example output
++
+[source,terminal]
+----
+Error: Error creating network Load Balancer: AccessDenied: User: arn:aws:sts::970xxxxxxxxx:assumed-role/ManagedOpenShift-Installer-Role/163xxxxxxxxxxxxxxxx is not authorized to perform: iam:CreateServiceLinkedRole on resource: arn:aws:iam::970xxxxxxxxx:role/aws-service-role/elasticloadbalancing.amazonaws.com/AWSServiceRoleForElasticLoadBalancing"
+----
+
+. If you receive the above error during cluster creation, run the following command:
++
+[source,terminal]
+----
+aws iam get-role --role-name "AWSServiceRoleForElasticLoadBalancing" || aws iam create-service-linked-role --aws-service-name "elasticloadbalancing.amazonaws.com"
+----
+
+== Logging in to your Red Hat account
+. Enter `rosa login` in a terminal.
+. It will prompt you to open a web browser and go to the link:https://console.redhat.com/openshift/token/rosa[Red Hat console].
+. Log in, if necessary.
+. Click *Load token*.
+. Copy the token, paste it into the CLI prompt, and press enter.  Alternatively, you can copy the full `rosa login --token=abc...` command and paste it in the terminal.
++
+image::cloud-experts-getting-started-setup-token.png[]
+
+== Verifying credentials
+Verify that all the credentials are correct.
+
+. Run `rosa whoami` in the terminal.
++
+.Example output
+[source,terminal]
+----
+AWS Account ID:               000000000000
+AWS Default Region:           us-east-2
+AWS ARN:                      arn:aws:iam::000000000000:user/myuser
+OCM API:                      https://api.openshift.com
+OCM Account ID:               1DzGIdIhqEWy000000000000000
+OCM Account Name:             Your Name
+OCM Account Username:         [email protected]
+OCM Account Email:            [email protected]
+OCM Organization ID:          1HopHfA20000000000000000000
+OCM Organization Name:        Red Hat
+OCM Organization External ID: 0000000
+----
+. Check the information for accuracy before proceeding.
+
+== Verifying quota
+Verify that your AWS account has ample quota in the region in which you will be deploying your cluster.  
+
+* Run the following command:
++
+[source,terminal]
+----
+rosa verify quota
+----
++
+.Example output
++
+[source,terminal]
+----
+I: Validating AWS quota...
+I: AWS quota ok.
+----
+
+* If cluster installation fails, validate the actual AWS resource usage against the xref:../../rosa_planning/rosa-sts-required-aws-service-quotas.adoc#rosa-sts-required-aws-service-quotas[AWS service quotas].
+
+== Verifying the `oc` CLI
+Verify that the `oc` CLI is installed correctly:
+
+[source,terminal]
+----
+rosa verify openshift-client
+----
+
+You have now successfully set up you account and environment. You are ready to deploy your cluster.
+
+//== Deploying a cluster
+//In the next section you will deploy your cluster.  There are two mechanisms to do so:
+
+//- Using the ROSA CLI
+//- Using the OCM Web User Interface
+
+//Either way is perfectly fine for the purposes of this workshop. Though keep in mind that if you are using the OCM UI, there will be a few extra steps to set it up in order to deploy into your AWS account for the first time.  This will not need to be repeated for subsequent deployments using the OCM UI for the same AWS account.
+
+//Please select the desired mechanism in the left menu under "Deploy the cluster".
+
+//*[ROSA]: Red Hat OpenShift Service on AWS
+//*[STS]: AWS Security Token Service
+//*[OCM]: OpenShift Cluster Manager

cloud_experts_tutorials/cloud_experts_getting_started/images

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

cloud_experts_tutorials/cloud_experts_getting_started/modules

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

cloud_experts_tutorials/cloud_experts_getting_started/snippets

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