Merge pull request #91212 from bergerhoffer/OSDOCS-13254-web-tutorial

OSDOCS#13454: Updates to the web console tutorial

Author: bergerhoffer

images/fa-plus-circle.png

@@ -12,10 +12,14 @@ Cluster administrators can allow developers to create their own projects. In mos
 
 This procedure creates a new project called `user-getting-started`. You will use this project throughout the rest of this tutorial.
 
+[IMPORTANT]
+====
+If you are using Developer Sandbox to complete this tutorial, skip this procedure. A project has already been created for you.
+====
+
 .Prerequisites
 
-* You have access to an {product-title} cluster.
-* You have installed the OpenShift CLI (`oc`).
+* You have logged in to the {oc-first}.
 
 .Procedure
 

images/getting-started-examine-pod.png

@@ -6,11 +6,11 @@
 [id="getting-started-cli-creating-secret_{context}"]
 = Providing access to the database by creating a secret
 
-The `nationalparks` application needs information, such as the database name, username, and passwords, on how to access the MongoDB database. However, because this information is sensitive, you should not store it directly in the pod.
+The `nationalparks` application needs information, such as the database name, username, and passwords, to access the MongoDB database. However, because this information is sensitive, you should not store it directly in the pod.
 
 You can use a _secret_ to store sensitive information, and share that secret with workloads.
 
-`Secret` objects provide a mechanism to hold sensitive information such as passwords, {product-title} client configuration files, private source repository credentials, and so on. Secrets decouple sensitive content from the pods. You can mount secrets into containers by using a volume plugin, or the system can use secrets to perform actions on behalf of a pod.
+`Secret` objects provide a mechanism to hold sensitive information such as passwords, {product-title} client configuration files, and private source repository credentials. Secrets decouple sensitive content from the pods. You can mount secrets into containers by using a volume plugin or by passing the secret in as an environment variable. The system can then use secrets to provide the pod with the sensitive information.
 
 The following procedure creates the `nationalparks-mongodb-parameters` secret and mounts it to the `nationalparks` workload.
 

images/getting-started-parksmap-url.png

@@ -26,3 +26,8 @@ As a requirement of the application, you must assign the `view` role to the `def
 ----
 $ oc adm policy add-role-to-user view -z default -n user-getting-started
 ----
++
+[IMPORTANT]
+====
+If you are using a different project, replace `user-getting-started` with the name of your project.
+====

images/getting-started-scaling-pod.png

@@ -34,7 +34,9 @@ NAME       HOST/PORT                                                  PATH   SER
 parksmap   parksmap-user-getting-started.apps.cluster.example.com            parksmap    8080-tcp   edge          None
 ----
 
-. From the above output, copy the value in the `HOST/PORT` column. Because the route is a secured route, you must add `https://` in front to get the application URL.
+. From the above output, copy the value in the `HOST/PORT` column.
+
+. Add `https://` in front of the copied value to get the application URL. This is necessary because the route is a secured route.
 +
 .Example application URL
 [source,text]
@@ -45,4 +47,6 @@ https://parksmap-user-getting-started.apps.cluster.example.com
 . Paste this application URL into your web browser. Your browser should display a map of the national parks across the world.
 +
 .National parks across the world
-image::getting-started-map-national-parks.png[A map of the national parks across the world is displayed with location tracking.]
+image::getting-started-map-national-parks.png[Map of the national parks across the world]
++
+If you allow the application to access your location, the map will center on your location.

modules/getting-started-cli-creating-new-project.adoc

@@ -1,32 +1,30 @@
 // Module included in the following assemblies:
 //
-// * getting-started/openshift-web-console.adoc
+// * tutorials/dev-app-web-console.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="getting-started-web-console-connecting-database_{context}"]
-= Connecting to a database
+= Deploying the database application
 
-Deploy and connect a MongoDB database where the `national-parks-app` application stores location information.
-Once you mark the `national-parks-app` application as a backend for the map visualization tool, `parksmap` deployment uses the {product-title} discover mechanism to display the map automatically.
+The following procedure deploys `mongodb-nationalparks`, which is a MongoDB database that will hold the national park location information.
 
 .Prerequisites
 
-* You are logged in to the {product-title} web console.
-* You are in the *Developer* perspective.
-* You have a deployed image.
+* You have deployed the `parksmap` front-end application.
+* You have deployed the `nationalparks` back-end application.
 
 .Procedure
 
-. From the *+Add* view in the *Developer* perspective, click *Container images* to open a dialog.
-. In the *Image Name* field, enter `quay.io/centos7/mongodb-36-centos7`.
-. In the *Runtime icon* field, search for `mongodb`.
-. Scroll down to the *General* section.
-. Ensure that you have the current values for the following:
-.. Application: `national-parks-app`
-.. Name: `mongodb-nationalparks`
-. Select *Deployment* as the *Resource*.
-. Unselect the checkbox next to *Create route to the application*.
-. In the *Advanced Options* section, click *Deployment* to add environment variables to add the following environment variables:
+. From the *Quick create* (image:fa-plus-circle.png[title="Quick create menu"]) menu in the upper right corner, click *Container images*.
+. Select *Image name from external registry* and enter `registry.redhat.io/rhmap47/mongodb`.
+. In the *Runtime icon* field, search for and select `mongodb`.
+. Scroll to the *General* section.
+. In the *Application name* field, enter `national-parks-app`.
+. In the *Name* field, enter `mongodb-nationalparks`.
+. Scroll to the *Deploy* section.
+. In the *Resource type* field, ensure that *Deployment* is selected.
+. Click *Show advanced Deployment option*.
+. Under *Environment variables (runtime only)*, add the following names and values:
 +
 .Environment variable names and values
 [cols="1,1"]
@@ -38,5 +36,16 @@ Once you mark the `national-parks-app` application as a backend for the map visu
 |`MONGODB_DATABASE`|`mongodb`
 |`MONGODB_ADMIN_PASSWORD`|`mongodb`
 |===
++
+[TIP]
+====
+Click *Add value* to add each additional environment variable.
+====
+
+. In the *Advanced options* section, clear *Create a route*.
++
+The database application does not need to be accessed externally, so a route is not required.
 
 . Click *Create*.
+
+You are redirected to the *Topology* page where you can see the `mongodb-nationalparks` deployment in the `national-parks-app` application.

modules/getting-started-cli-creating-secret.adoc

@@ -1,33 +1,29 @@
 // Module included in the following assemblies:
 //
-// * getting-started/openshift-web-console.adoc
+// * tutorials/dev-app-web-console.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="getting-started-web-console-creating-new-project_{context}"]
-= Creating a new project
+= Creating a project
 
-A project enables a community of users to organize and manage their content in isolation. Projects are {product-title} extensions to Kubernetes namespaces. Projects have additional features that enable user self-provisioning.
+A _project_ enables a community of users to organize and manage their content in isolation. Projects are {product-title} extensions to Kubernetes namespaces. Projects have additional features that enable user self-provisioning. Each project has its own set of objects, policies, constraints, and service accounts.
 
-Users must receive access to projects from administrators. Cluster administrators can allow developers to create their own projects. In most cases, users automatically have access to their own projects.
+Cluster administrators can allow developers to create their own projects. In most cases, you automatically have access to your own projects. Administrators can grant access to other projects as needed.
 
-Each project has its own set of objects, policies, constraints, and service accounts.
+This procedure creates a new project called `user-getting-started`. You will use this project throughout the rest of this tutorial.
+
+[IMPORTANT]
+====
+If you are using Developer Sandbox to complete this tutorial, skip this procedure. A project has already been created for you.
+====
 
 .Prerequisites
 
-* You are logged in to the {product-title} web console.
-* You are in the *Developer* perspective.
-* You have the appropriate roles and permissions in a project to create applications and other workloads in {product-title}.
+* You have logged in to the {product-title} web console.
 
 .Procedure
 
-. In the *+Add* view, select *Project* -> *Create Project*.
+. Navigate to *Home* -> *Projects*.
+. Click *Create Project*.
 . In the *Name* field, enter `user-getting-started`.
-. Optional: In the *Display name* field, enter `Getting Started with OpenShift`.
-+
-[NOTE]
-====
-*Display name* and *Description* fields are optional.
-====
 . Click *Create*.
-
-You have created your first project on {product-title}.

modules/getting-started-cli-granting-permissions.adoc

@@ -1,43 +1,52 @@
 // Module included in the following assemblies:
 //
-// * getting-started/openshift-web-console.adoc
+// * tutorials/dev-app-web-console.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="getting-started-web-console-creating-secret_{context}"]
-= Creating a secret
+= Providing access to the database by creating a secret
 
-The `Secret` object provides a mechanism to hold sensitive information such as passwords, {product-title} client configuration files, private source repository credentials, and so on.
-Secrets decouple sensitive content from the pods. You can mount secrets into containers using a volume plugin or the system can use secrets to perform actions on behalf of a pod.
-The following procedure adds the secret `nationalparks-mongodb-parameters` and mounts it to the `nationalparks` workload.
+The `nationalparks` application needs information, such as the database name, username, and passwords, to access the MongoDB database. However, because this information is sensitive, you should not store it directly in the pod.
+
+You can use a _secret_ to store sensitive information, and share that secret with workloads.
+
+`Secret` objects provide a mechanism to hold sensitive information such as passwords, {product-title} client configuration files, and private source repository credentials. Secrets decouple sensitive content from the pods. You can mount secrets into containers by using a volume plugin or by passing the secret in as an environment variable. The system can then use secrets to provide the pod with the sensitive information.
+
+The following procedure creates the `nationalparks-mongodb-parameters` secret and mounts it to the `nationalparks` workload.
 
 .Prerequisites
 
-* You are logged in to the {product-title} web console.
-* You are in the *Developer* perspective.
-* You have a deployed image.
+* You have deployed the `nationalparks` back-end application.
+* You have deployed the `mongodb-nationalparks` database application.
 
 .Procedure
 
-. From the *Developer* perspective, navigate to *Secrets* on the left hand navigation and click *Secrets*.
+. Navigate to *Workloads* -> *Secrets*.
 . Click *Create* -> *Key/value secret*.
-.. In the *Secret name* field, enter `nationalparks-mongodb-parameters`.
-.. Enter the following values for *Key* and *Value*:
+. In the *Secret name* field, enter `nationalparks-mongodb-parameters`.
+. Enter the following values for *Key* and *Value*:
 +
 .Secret keys and values
 [cols="1,1"]
 |===
 |Key |Value
 
-|`MONGODB_USER`|`mongodb`
 |`DATABASE_SERVICE_NAME`|`mongodb-nationalparks`
+|`MONGODB_USER`|`mongodb`
 |`MONGODB_PASSWORD`|`mongodb`
 |`MONGODB_DATABASE`|`mongodb`
 |`MONGODB_ADMIN_PASSWORD`|`mongodb`
 |===
++
+[TIP]
+====
+Click *Add key/value* to add each additional key/value pair.
+====
 
-.. Click *Create*.
+. Click *Create*.
 . Click *Add Secret to workload*.
-.. From the drop down menu, select `nationalparks` as the workload to add.
-.. Click *Save*.
+. From the *Add this secret to workload* list, select `nationalparks`.
+
+. Click *Save*.
 
 This change in configuration triggers a new rollout of the `nationalparks` deployment with the environment variables properly injected.

modules/getting-started-cli-login.adoc

@@ -1,32 +1,38 @@
 // Module included in the following assemblies:
 //
-// * getting-started/openshift-web-console.adoc
+// * tutorials/dev-app-web-console.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="getting-started-web-console-deploying-first-image_{context}"]
-= Deploying your first image
+= Deploying the front-end application
 
-The simplest way to deploy an application in {product-title} is to run an existing container image. The following procedure deploys a front end component of an application called `national-parks-app`. The web application displays an interactive map. The map displays the location of major national parks across the world.
+The simplest way to deploy an application in {product-title} is to run a provided container image.
 
-.Prerequisites
-
-* You are logged in to the {product-title} web console.
-* You are in the *Developer* perspective.
-* You have the appropriate roles and permissions in a project to create applications and other workloads in {product-title}.
+The following procedure deploys `parksmap`, which is the front-end component of the `national-parks-app` application. The web application displays an interactive map of the locations of national parks across the world.
 
 .Procedure
 
-. From the *+Add* view in the *Developer* perspective, click *Container images* to open a dialog.
-. In the *Image Name* field, enter the following: `quay.io/openshiftroadshow/parksmap:latest`
-. Ensure that you have the current values for the following:
-.. Application: `national-parks-app`
-.. Name: `parksmap`
-. Select *Deployment* as the *Resource*.
-. Select *Create route to the application*.
-. In the *Advanced Options* section, click *Labels* and add labels to better identify this deployment later. Labels help identify and filter components in the web console and in the command line. Add the following labels:
+. From the *Quick create* (image:fa-plus-circle.png[title="Quick create menu"]) menu in the upper right corner, click *Container images*.
+. Select *Image name from external registry* and enter `quay.io/openshiftroadshow/parksmap:latest`.
+. Scroll to the *General* section.
+. In the *Application name* field, enter `national-parks-app`.
+. In the *Name* field, ensure that the value is `parksmap`.
+. Scroll to the *Deploy* section.
+. In the *Resource type* field, ensure that *Deployment* is selected.
+. In the *Advanced options* section, ensure that *Create a route* is selected.
++
+By default, services running on {product-title} are not accessible externally. You must select this option to create a route so that external clients can access your service.
+
+. Click the *Labels* hyperlink.
++
+The application code requires certain labels to be set.
+
+. Add the following labels to the text area and press Enter after each key/value pair:
+
 ** `app=national-parks-app`
 ** `component=parksmap`
 ** `role=frontend`
+
 . Click *Create*.
 
 You are redirected to the *Topology* page where you can see the `parksmap` deployment in the `national-parks-app` application.