Merge pull request #90215 from bergerhoffer/OSDOCS-13467-tutorial

OSDOCS:13467: Creating new tutorial book and updating CLI tutorial

Author: bergerhoffer

_topic_maps/_topic_map.yml

@@ -59,18 +59,16 @@ Topics:
 - Name: Additional release notes
   File: addtl-release-notes
 ---
-Name: Getting started
-Dir: getting_started
+Name: Tutorials
+Dir: tutorials
 Distros: openshift-enterprise
 Topics:
-- Name: Kubernetes overview
-  File: kubernetes-overview
-- Name: OpenShift Container Platform overview
-  File: openshift-overview
-- Name: Web console walkthrough
-  File: openshift-web-console
-- Name: Command-line walkthrough
-  File: openshift-cli
+# - Name: Tutorials overview
+#   File: index
+- Name: Deploying an application by using the web console
+  File: dev-app-web-console
+- Name: Deploying an application by using the CLI
+  File: dev-app-cli
 ---
 Name: Architecture
 Dir: architecture

getting_started/accessing-your-services.adoc

@@ -1,46 +1,41 @@
 // Module included in the following assemblies:
 //
-// * getting-started/openshift-cli.adoc
+// * tutorials/dev-app-cli.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="getting-started-cli-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 must have access to an {product-title} cluster.
-* You must have installed the OpenShift CLI (`oc`).
-* You have a deployed image.
+* You have deployed the `parksmap` front-end application.
+* You have deployed the `nationalparks` back-end application.
 
 .Procedure
 
-* To connect to a database, enter the following command:
+* Deploy the `mongodb-nationalparks` database application by running the following command:
 +
 [source,terminal]
 ----
-$ oc new-app quay.io/centos7/mongodb-36-centos7:master --name mongodb-nationalparks -e MONGODB_USER=mongodb -e MONGODB_PASSWORD=mongodb -e MONGODB_DATABASE=mongodb -e MONGODB_ADMIN_PASSWORD=mongodb -l 'app.kubernetes.io/part-of=national-parks-app,app.kubernetes.io/name=mongodb'
+$ oc new-app registry.redhat.io/rhmap47/mongodb --name mongodb-nationalparks -e MONGODB_USER=mongodb -e MONGODB_PASSWORD=mongodb -e MONGODB_DATABASE=mongodb -e MONGODB_ADMIN_PASSWORD=mongodb -l 'app.kubernetes.io/part-of=national-parks-app,app.kubernetes.io/name=mongodb'
 ----
 +
 .Example output
 +
-[source,terminal]
+[source,text]
 ----
---> Found container image dc18f52 (3 years old) from quay.io for "quay.io/centos7/mongodb-36-centos7:master"
-
-    MongoDB 3.6 
-    ----------- 
-    MongoDB (from humongous) is a free and open-source cross-platform document-oriented database program. Classified as a NoSQL database program, MongoDB uses JSON-like documents with schemas. This container image contains programs to run mongod server.
-
-    Tags: database, mongodb, rh-mongodb36
+--> Found container image 7a61087 (12 days old) from quay.io for "quay.io/mongodb/mongodb-enterprise-server"
 
-    * An image stream tag will be created as "mongodb-nationalparks:master" that will track this image
+    * An image stream tag will be created as "mongodb-nationalparks:latest" that will track this image
 
 --> Creating resources with label app.kubernetes.io/name=mongodb,app.kubernetes.io/part-of=national-parks-app ...
     imagestream.image.openshift.io "mongodb-nationalparks" created
     deployment.apps "mongodb-nationalparks" created
     service "mongodb-nationalparks" created
 --> Success
+    Application is not exposed. You can expose services to the outside world by executing one or more of the commands below:
+     'oc expose service/mongodb-nationalparks'
+    Run 'oc status' to view your app.
 ----

getting_started/dedicated-networking.adoc

@@ -1,34 +1,35 @@
 // Module included in the following assemblies:
 //
-// * getting-started/openshift-cli.adoc
+// * tutorials/dev-app-cli.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="getting-started-cli-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.
 
 .Prerequisites
 
-* You must have access to an {product-title} cluster.
-* You must have installed the OpenShift CLI (`oc`).
+* You have access to an {product-title} cluster.
+* You have installed the OpenShift CLI (`oc`).
 
 .Procedure
 
-* To create a new project, enter the following command:
+* Create a project by running the following command:
 +
 [source,terminal]
 ----
-$ oc new-project user-getting-started --display-name="Getting Started with OpenShift"
+$ oc new-project user-getting-started
 ----
 +
 .Example output
 
 [source,terminal]
 ----
 Now using project "user-getting-started" on server "https://openshift.example.com:6443".
+...
 ----

getting_started/deleting-your-cluster.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * tutorials/dev-app-cli.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="getting-started-cli-creating-route-backend_{context}"]
+= Exposing the back-end service
+
+Similar to how you exposed the front-end service for external clients, you must now expose the back-end service by creating a route.
+
+.Prerequisites
+
+* You have deployed the `nationalparks` back-end application.
+* You have `cluster-admin` or project-level `admin` privileges.
+
+.Procedure
+
+. Create a route to expose the `nationalparks` back-end application by running the following command:
++
+[source,terminal]
+----
+$ oc create route edge nationalparks --service=nationalparks
+----
+
+. Label the `nationalparks` route by running the following command:
++
+[source,terminal]
+----
+$ oc label route nationalparks type=parksmap-backend
+----
++
+The application code expects the `nationalparks` route to be labeled with `type=parksmap-backend`.

getting_started/openshift-cli.adoc

@@ -1,58 +1,39 @@
 // Module included in the following assemblies:
 //
-// * getting-started/openshift-cli.adoc
+// * tutorials/dev-app-cli.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="getting-started-cli-creating-route_{context}"]
-= Creating a route
+= Exposing the front-end service
 
-External clients can access applications running on {product-title} through the routing layer and the data object behind that is a _route_. The default {product-title} router (HAProxy) uses the HTTP header of the incoming request to determine where to proxy the connection.
+By default, services running on {product-title} are not accessible externally.
+
+To expose your service so that external clients can access it, you can create a _route_. A `Route` object is a {product-title} networking resource similar to a Kubernetes `Ingress` object. The default {product-title} router (HAProxy) uses the HTTP header of the incoming request to determine where to proxy the connection.
 
 Optionally, you can define security, such as TLS, for the route.
 
 .Prerequisites
 
-* You must have access to an {product-title} cluster.
-* You must have installed the OpenShift CLI (`oc`).
-* You have a deployed image.
-* You must have `cluster-admin` or `project-admin` privileges.
+* You have deployed the `parksmap` front-end application.
+* You have `cluster-admin` or project-level `admin` privileges.
 
 .Procedure
 
-. To retrieve the created application service, enter the following command:
-+
-[source,terminal]
-----
-$ oc get service
-----
-+
-.Example output
-+
-[source,terminal]
-----
-NAME      TYPE       CLUSTER-IP         EXTERNAL-IP    PORT(S)   AGE
-parksmap  ClusterIP  <your-cluster-IP>  <123.456.789>  8080/TCP  8m29s
-----
+* Create a route to expose the `parksmap` front-end application by running the following command:
 
-. To create a route, enter the following command:
 +
 [source,terminal]
 ----
 $ oc create route edge parksmap --service=parksmap
 ----
-+
-.Example output
-+
-[source,terminal]
-----
-route.route.openshift.io/parksmap created
-----
 
-. To retrieve the created application route, enter the following command:
+.Verification
+
+* Verify that the application route was successfully created by running the following command:
 +
 [source,terminal]
 ----
-$ oc get route
+$ oc get route parksmap
 ----
 +
 .Example output