Merge pull request #68592 from ShaunaDiaz/OSDOCS-8778

OSDOCS-8778: refactor Running apps book

Author: ShaunaDiaz

_topic_maps/_topic_map_ms.yml

@@ -428,20 +428,20 @@ Name: Running applications
 Dir: microshift_running_apps
 Distros: microshift
 Topics:
+- Name: Using Kustomize to deploy applications
+  File: microshift-applications
 - Name: Embedding applications on RHEL for Edge
   File: microshift-embedded-apps-on-rhel-edge
 - Name: Embedding applications for offline use
   File: microshift-embed-apps-offline-use
 - Name: Embedding applications tutorial
   File: microshift-embedding-apps-tutorial
-- Name: Deploying applications
-  File: microshift-applications
-- Name: Using operators
-  File: microshift-operators
-- Name: Greenboot workload health check scripts
+- Name: Creating application or workload health check scripts
   File: microshift-greenboot-workload-scripts
 - Name: Pod security authentication and authorization
   File: microshift-authentication
+- Name: Using Operators
+  File: microshift-operators
 ---
 Name: Backup and restore
 Dir: microshift_backup_and_restore

microshift_running_apps/microshift-applications.adoc

@@ -1,12 +1,12 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="applications-with-microshift"]
-= Application deployment with {microshift-short}
+= Using Kustomize manifests to deploy applications
 include::_attributes/attributes-microshift.adoc[]
 :context: applications-microshift
 
 toc::[]
 
-You can use the `kustomize` configuration management tool to deploy applications. Read through the following procedure for an example of how this tool works in {microshift-short}.
+You can use the `kustomize` configuration management tool with application manifests to deploy applications. Read through the following procedures for an example of how Kustomize works in {microshift-short}.
 
 include::modules/microshift-manifests-overview.adoc[leveloffset=+1]
 

microshift_running_apps/microshift-operators.adoc

@@ -15,4 +15,4 @@ Operators offer a more localized configuration experience and integrate with Kub
 [id="how-to-install-operators_{context}"]
 == How to install Operators in {microshift-short}
 
-To minimize the footprint of {microshift-short}, Operators are installed directly with manifests instead of using the Operator Lifecycle Manager (OLM). You can use the `kustomize` configuration management tool with {microshift-short} to deploy an application. Use the same steps to install Operators with manifests. Read xref:../microshift_running_apps/microshift-applications.adoc#microshift-manifests-overview_applications-microshift[Application deployment with {microshift-short}] for more information about manifests.
+To minimize the footprint of {microshift-short}, Operators are installed directly with manifests instead of using the Operator Lifecycle Manager (OLM). You can use the `kustomize` configuration management tool with {microshift-short} to deploy an application. Use the same steps to install Operators with manifests. Read xref:../microshift_running_apps/microshift-applications.adoc#microshift-manifests-overview_applications-microshift[Using Kustomize manifests to deploy applications] for more information about manifests.

modules/microshift-manifests-overview.adoc

@@ -4,11 +4,33 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="microshift-manifests-overview_{context}"]
-= How manifests work with kustomize
+= How Kustomize works with manifests to deploy applications
 
-The `kustomize` configuration management tool is integrated with {microshift-short}. At every start, {microshift-short} searches the `/etc/microshift/manifests`, `/etc/microshift/manifests.d/++*++`, `/usr/lib/microshift/`, and `/usr/lib/microshift/manifests.d/++*++` manifest directories for a `kustomization.yaml`, `kustomization.yml`, or `Kustomization` file. If it finds one, {microshift-short} automatically runs the equivalent of the `kubectl apply -k` command to apply the identified manifests to the cluster.
+The `kustomize` configuration management tool is integrated with {microshift-short}. You can use Kustomize and the {oc-first} together to apply customizations to your application manifests and deploy those applications to a {microshift-short} cluster.
 
-Loading from multiple directories allows you to manage {microshift-short} workloads with more flexibility. Different workloads can be independent of each other.
+* A `kustomization.yaml` file is a specification of resources plus customizations.
+* Kustomize uses a `kustomization.yaml` file to load a resource, such as an application, then applies any changes you want to that application manifest and produces a copy of the manifest with the changes overlaid.
+* Using a manifest copy with an overlay keeps the original configuration file for your application intact, while enabling you to deploy iterations and customizations of your applications efficiently.
+* You can then deploy the application in your {microshift-short} cluster with an `oc` command.
+
+[id="how-microshift-uses-manifests"]
+== How {microshift-short} uses manifests
+At every start, {microshift-short} searches the following manifest directories for Kustomize manifest files:
+
+* `/etc/microshift/manifests`
+* `/etc/microshift/manifests.d/++*++`
+* `/usr/lib/microshift/
+* `/usr/lib/microshift/manifests.d/++*++`
+
+{microshift-short} automatically runs the equivalent of the `kubectl apply -k` command to apply the manifests to the cluster if any of the following file types exists in the searched directories:
+
+* `kustomization.yaml`
+* `kustomization.yml`
+* `Kustomization`
+
+This automatic loading from multiple directories means you can manage {microshift-short} workloads with the flexibility of having different workloads run independently of each other.
+
+.{microshift-short} manifest directories
 
 [cols="2",options="header"]
 |===