OSDOCS-3033 - Adding a ROSA quick start guide

Author: pneedle-rh

_topic_maps/_topic_map_rosa.yml

@@ -49,11 +49,18 @@ Topics:
 - Name: Planning your environment
   File: rosa-planning-environment
 ---
-Name: Setting up accounts and clusters using AWS security token service (STS)
+Name: Getting started
+Dir: rosa_getting_started
+Distros: openshift-rosa
+Topics: 
+- Name: Getting started with ROSA
+  File: rosa-getting-started
+---
+Name: Setting up accounts and clusters using AWS Security Token Service (STS)
 Dir: rosa_getting_started_sts
 Distros: openshift-rosa
 Topics:
-- Name: Getting started using STS workflow
+- Name: Understanding the ROSA with STS deployment workflow
   File: rosa-sts-getting-started-workflow
 - Name: AWS prerequisites for ROSA with STS
   File: rosa-sts-aws-prereqs
@@ -85,7 +92,7 @@ Name: Setting up accounts and clusters
 Dir: rosa_getting_started
 Distros: openshift-rosa
 Topics:
-- Name: Getting started workflow
+- Name: Understanding the ROSA deployment workflow
   File: rosa-getting-started-workflow
 - Name: AWS prerequisites for ROSA
   File: rosa-aws-prereqs

modules/deploy-app.adoc

@@ -1,35 +1,34 @@
-
 // Module included in the following assemblies:
 //
-// * assemblies/quickstart-osd.adoc
+// * rosa_getting_started/rosa-getting-started.adoc
+// * osd_quickstart/osd-quickstart.adoc
 
 [id="deploy-app_{context}"]
-= Deploying an app with the OpenShift service catalog
-
+= Deploying an application from the Developer Catalog
 
-From the OpenShift web console, you can deploy one of the built-in service catalog apps and expose the app with a route.
+From the {product-title} web console, you can deploy a test application from the Developer Catalog and expose it with a route.
 
 .Prerequisites
 
-- An actively running cluster.
+* You have access to a {product-title} cluster.
 
 .Procedure
 
-. From OpenShift Cluster Manager (OCM), click *Open console*.
+. From {console-redhat-com}, navigate to the overview page for your cluster and select *Open console*.
 
-. From the side navigation menu in the *Administrator* perspective, click *Home* -> *Projects* and then click *Create Project*.
+. In the *Administrator* perspective, select *Home* -> *Projects* -> *Create Project*.
 
-. Enter a name for your project. Optional: Add a *Display Name* and *Description*. Click *Create*.
+. Enter a name for your project and optionally add a *Display Name* and *Description*.
 
-. Switch to the Developer perspective from the side navigation menu to create an app.
+. Click *Create* to create the project.
 
-. Click *+Add* from the side navigation menu. From the *Add pane* menu bar, make sure that the *Project* is the one that you just created.
+. Switch to the *Developer* perspective and select *+Add*. Make sure that the selected *Project* is the one that you just created.
 
-. Click *From Catalog*. The Developer Catalog opens in the pane.
+. In the *Developer Catalog* dialog, select *All services*.
 
-. From the navigation menu in the pane, click *Languages* -> *JavaScript*.
+. In the *Developer Catalog* page, select *Languages* -> *JavaScript* from the menu.
 
-. Click *Node.js*, and then click *Create Application*. After you select *Node.js*, the *Create Source-to-Image Application* pane opens.
+. Click *Node.js*, and then click *Create Application* to open the *Create Source-to-Image Application* page.
 +
 [NOTE]
 ====
@@ -38,23 +37,26 @@ You might need to click *Clear All Filters* to display the *Node.js* option.
 
 . In the *Git* section, click *Try Sample*.
 
-. Scroll to confirm that *Deployment* and *Create a route to the application* are selected.
+. Add a unique name in the *Name* field. The value will be used to name the associated resources.
 
-. Click *Create*. It will take a few minutes for the pods to deploy.
+. Confirm that *Deployment* and *Create a route to the application* are selected.
 
-. Optional: You can check the status of the pods from the *Topology* pane. Click your *nodejs* app and review its sidebar. You must see that the `nodejs` build is complete, and that the `nodejs` pod is in a *Running* state to continue.
+. Click *Create* to deploy the application. It will take a few minutes for the pods to deploy.
 
-. When the deployment is complete, click the route location URL, which has a format similar to the following:
+. Optional: Check the status of the pods in the *Topology* pane by selecting your *nodejs* app and reviewing its sidebar. You must wait for the `nodejs` build to complete and for the `nodejs` pod to be in a *Running* state before continuing.
+
+. When the deployment is complete, click route URL for the application, which has a format similar to the following:
 +
 ----
-http://nodejs-<project>.<cluster_name>-<hash>.<region>.containers.appdomain.cloud
+http://nodejs-<project>.<cluster_name>.<hash>.<region>.openshiftapps.com/
 ----
 +
-
 A new tab in your browser opens with a message similar to the following.
 +
 ----
 Welcome to your Node.js application on OpenShift
 ----
 
-. Optional: To clean up the resources that you created, select *Administrator* from the perspective switcher, navigate to *Home* -> *Projects*, click your project's action menu, and click *Delete Project*.
+. Optional: Delete the application and clean up the resources that you created:
+.. In the *Administrator* perspective, navigate to *Home* -> *Projects*.
+.. Click the action menu for your project and select *Delete Project*.

modules/rosa-accessing-your-cluster.adoc

@@ -49,8 +49,12 @@ Any optional fields can be left empty and a default will be selected.
 ...
 ----
 +
-.. Follow the URL from the output. This creates a new OAuth application in the GitHub organization you specified.
-.. Click *Register application* to access your client ID and client secret.
+.. Follow the URL in the output and select *Register application* to register a new OAuth application in your GitHub organization. By registering the application, you enable the OAuth server that is built into ROSA to authenticate members of your GitHub organization into your cluster.
++
+[NOTE]
+====
+The fields in the *Register a new OAuth application* GitHub form are automatically filled with the required values through the URL that is defined by the `rosa` CLI tool.
+====
 .. Use the information from the GitHub application you created and continue the prompts. Enter the following values:
 +
 --

modules/rosa-create-objects.adoc

@@ -58,7 +58,7 @@ Create a cluster administrator that can log in to a cluster named `mycluster`:
 $ rosa create admin --cluster=mycluster
 ----
 
-[id="rosa-create-cluster_{context}"]
+[id="rosa-create-cluster-command_{context}"]
 == create cluster
 
 Create a new cluster.

modules/rosa-getting-started-access-cluster-web-console.adoc

@@ -0,0 +1,37 @@
+// Module included in the following assemblies:
+//
+// * rosa_getting_started/rosa-getting-started.adoc
+
+[id="rosa-getting-started-access-cluster-web-console_{context}"]
+= Accessing a cluster through the web console
+
+After you have created a cluster administrator user or added a user to your configured identity provider, you can log into your {product-title} (ROSA) cluster through the web console.
+
+.Prerequisites
+
+* You have an AWS account.
+* You installed and configured the latest AWS (`aws`), ROSA (`rosa`), and OpenShift (`oc`) CLIs on your workstation.
+* You logged in to your Red Hat account by using the `rosa` CLI.
+* You created a ROSA cluster.
+* You have created a cluster administrator user or added your user account to the configured identity provider.
+
+.Procedure
+
+. Obtain the console URL for your cluster:
++
+[source,terminal]
+----
+$ rosa describe cluster -c <cluster_name> | grep Console <1>
+----
+<1> Replace `<cluster_name>` with the name of your cluster.
++
+.Example output
+[source,terminal]
+----
+Console URL:                https://console-openshift-console.apps.example-cluster.wxyz.p1.openshiftapps.com
+----
+
+. Go to the console URL in the output of the preceding step and log in.
++
+* If you created a `cluster-admin` user, log in by using the provided credentials.
+* If you configured an identity provider for your cluster, select the identity provider name in the *Log in with...* dialog and complete any authorization requests that are presented by your provider.

modules/rosa-getting-started-configure-an-idp-and-grant-access.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * rosa_getting_started/rosa-getting-started.adoc
+
+[id="rosa-getting-started-configure-an-idp-and-grant-access_{context}"]
+= Configuring an identity provider and granting cluster access
+
+{product-title} (ROSA) includes a built-in OAuth server. After your ROSA cluster is created, you must configure OAuth to use an identity provider. You can then add members to your configured identity provider to grant them access to your cluster.
+
+You can also grant the identity provider users with `cluster-admin` or `dedicated-admin` privileges as required.

modules/rosa-getting-started-configure-an-idp.adoc

@@ -0,0 +1,93 @@
+// Module included in the following assemblies:
+//
+// * rosa_getting_started/rosa-getting-started.adoc
+
+[id="rosa-getting-started-configure-an-idp_{context}"]
+= Configuring an identity provider
+
+You can configure different identity provider types for your {product-title} (ROSA) cluster. Supported types include GitHub, GitHub Enterprise, GitLab, Google, LDAP, OpenID Connect and HTPassword identity providers.
+
+The following procedure configures a GitHub identity provider as an example.
+
+.Prerequisites
+
+* You have an AWS account.
+* You installed and configured the latest AWS (`aws`), ROSA (`rosa`), and OpenShift (`oc`) CLIs on your workstation.
+* You logged in to your Red Hat account by using the `rosa` CLI.
+* You created a ROSA cluster.
+* You have a GitHub user account.
+
+.Procedure
+
+. Go to link:https://github.com[github.com] and log in to your GitHub account.
+
+. If you do not have an existing GitHub organization to use for identity provisioning for your ROSA cluster, create one. Follow the steps in the link:https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch[GitHub documentation].
+
+. Configure a GitHub identity provider for your cluster that is restricted to the members of your GitHub organization.
+.. Configure an identity provider using the interactive mode:
++
+[source,terminal]
+----
+$ rosa create idp --cluster=<cluster_name> --interactive <1>
+----
+<1> Replace `<cluster_name>` with the name of your cluster.
++
+.Example output
+[source,terminal]
+----
+I: Interactive mode enabled.
+Any optional fields can be left empty and a default will be selected.
+? Type of identity provider: github
+? Identity provider name: github-1
+? Restrict to members of: organizations
+? GitHub organizations: <github_org_name> <1>
+? To use GitHub as an identity provider, you must first register the application:
+  - Open the following URL:
+    https://github.com/organizations/<github_org_name>/settings/applications/new?oauth_application%5Bcallback_url%5D=https%3A%2F%2Foauth-openshift.apps.<cluster_name>/<random_string>.p1.openshiftapps.com%2Foauth2callback%2Fgithub-1&oauth_application%5Bname%5D=<cluster_name>&oauth_application%5Burl%5D=https%3A%2F%2Fconsole-openshift-console.apps.<cluster_name>/<random_string>.p1.openshiftapps.com
+  - Click on 'Register application'
+...
+----
+<1> Replace `<github_org_name>` with the name of your GitHub organization.
+.. Follow the URL in the output and select *Register application* to register a new OAuth application in your GitHub organization. By registering the application, you enable the OAuth server that is built into ROSA to authenticate members of your GitHub organization into your cluster.
++
+[NOTE]
+====
+The fields in the *Register a new OAuth application* GitHub form are automatically filled with the required values through the URL defined by the `rosa` CLI tool.
+====
+.. Use the information from your GitHub OAuth application page to populate the remaining `rosa create idp` interactive prompts.
++
+.Continued example output
+[source,terminal]
+----
+...
+? Client ID: <github_client_id> <1>
+? Client Secret: [? for help] <github_client_secret> <2>
+? GitHub Enterprise Hostname (optional):
+? Mapping method: claim <3>
+I: Configuring IDP for cluster '<cluster_name>'
+I: Identity Provider 'github-1' has been created.
+   It will take up to 1 minute for this configuration to be enabled.
+   To add cluster administrators, see 'rosa grant user --help'.
+   To login into the console, open https://console-openshift-console.apps.<cluster_name>.<random_string>.p1.openshiftapps.com and click on github-1.
+----
+<1> Replace `<github_client_id>` with the client ID for your GitHub OAuth application.
+<2> Replace `<github_client_secret>` with a client secret for your GitHub OAuth application.
+<3> Specify `claim` as the mapping method.
++
+[NOTE]
+====
+It might take approximately two minutes for the identity provider configuration to become active. If you have configured a `cluster-admin` user, you can watch the OAuth pods redeploy with the updated configuration by running `oc get pods -n openshift-authentication --watch`.
+====
+.. Enter the following command to verify that the identity provider has been configured correctly:
++
+[source,terminal]
+----
+$ rosa list idps --cluster=<cluster_name>
+----
++
+.Example output
+[source,terminal]
+----
+NAME        TYPE      AUTH URL
+github-1    GitHub    https://oauth-openshift.apps.<cluster_name>.<random_string>.p1.openshiftapps.com/oauth2callback/github-1
+----

modules/rosa-getting-started-create-cluster-admin-user.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * rosa_getting_started/rosa-getting-started.adoc
+
+[id="rosa-getting-started-create-cluster-admin-user_{context}"]
+= Creating a cluster administrator user for quick cluster access
+
+Before configuring an identity provider, you can create a user with `cluster-admin` privileges for immediate access to your {product-title} (ROSA) cluster.
+
+[NOTE]
+====
+The cluster administrator user is useful when you need quick access to a newly deployed cluster. However, Red Hat recommends that you configure an identity provider and grant cluster administrator privileges to the identity provider users as required. For more information about setting up an identity provider for your ROSA cluster, see _Configuring an identity provider and granting cluster access_.
+====
+
+.Prerequisites
+
+* You have an AWS account.
+* You installed and configured the latest AWS (`aws`), ROSA (`rosa`), and OpenShift (`oc`) CLIs on your workstation.
+* You logged in to your Red Hat account by using the `rosa` CLI.
+* You created a ROSA cluster.
+
+.Procedure
+
+. Create a cluster administrator user:
++
+[source,terminal]
+----
+$ rosa create admin --cluster=<cluster_name> <1>
+----
+<1> Replace `<cluster_name>` with the name of your cluster.
++
+.Example output
+[source,terminal]
+----
+W: It is recommended to add an identity provider to login to this cluster. See 'rosa create idp --help' for more information.
+I: Admin account has been added to cluster '<cluster_name>'.
+I: Please securely store this generated password. If you lose this password you can delete and recreate the cluster admin user.
+I: To login, run the following command:
+
+   oc login https://api.example-cluster.wxyz.p1.openshiftapps.com:6443 --username cluster-admin --password d7Rca-Ba4jy-YeXhs-WU42J
+
+I: It may take up to a minute for the account to become active.
+----
++
+[NOTE]
+====
+It might take approximately one minute for the `cluster-admin` user to become active.
+====
+
+. Log in to the cluster through the CLI:
+.. Run the command provided in the output of the preceding step to log in:
++
+[source,terminal]
+----
+$ oc login <api_url> --username cluster-admin --password <cluster_admin_password> <1>
+----
+<1> Replace `<api_url>` and `<cluster_admin_password>` with the API URL and cluster administrator password for your environment.
+.. Verify if you are logged in to the ROSA cluster as the `cluster-admin` user:
++
+[source,terminal]
+----
+$ oc whoami
+----
++
+.Example output
+[source,terminal]
+----
+cluster-admin
+----