Merge pull request #39903 from abrennan89/SRVCOM-1580-2

abrennan89 · web-flow · commit db4a4341a9be · 2021-12-16T14:59:34.000-06:00
SRVCOM-1580: Update serverless docs structure
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3119,16 +3119,15 @@ Name: Serverless
 Dir: serverless
 Distros: openshift-enterprise
 Topics:
-# Release notes
 - Name: Release Notes
   File: serverless-release-notes
-# Support
-- Name: Support
-  File: serverless-support
-# Intro / getting started
-- Name: Getting started
-  File: serverless-getting-started
-# Installing
+- Name: Discover
+  Dir: discover
+  Topics:
+  - Name: Understanding Knative Eventing
+    File: serverless-understanding-eventing
+  - Name: Understanding Knative Serving
+    File: serverless-understanding-serving
 - Name: Install
   Dir: install
   Topics:
@@ -3138,10 +3137,35 @@ Topics:
     File: installing-knative-serving
   - Name: Installing Knative Eventing
     File: installing-knative-eventing
-  - Name: Upgrading the OpenShift Serverless Operator
-    File: upgrading-serverless
   - Name: Removing OpenShift Serverless
     File: removing-openshift-serverless
+- Name: Get started
+  File: serverless-getting-started
+- Name: Update
+  Dir: update
+  Topics:
+  - Name: Upgrading the OpenShift Serverless Operator
+    File: upgrading-serverless
+# develop
+# administer
+- Name: Monitor
+  Dir: monitor
+  Topics:
+  # logging
+  - Name: Cluster logging with OpenShift Serverless
+    File: cluster-logging-serverless
+  # Tracing
+  - Name: Tracing requests using Jaeger
+    File: serverless-tracing
+  # monitoring services
+  - Name: Monitoring Knative services
+    File: serverless-service-monitoring
+  # Metrics
+  - Name: Metrics
+    File: serverless-serving-metrics
+# Support
+- Name: Support
+  File: serverless-support
 # Admin guide
 - Name: Administration guide
   Dir: admin_guide
@@ -3179,35 +3203,18 @@ Topics:
     File: serverless-custom-domains
   - Name: Using a custom TLS certificate for domain mapping
     File: serverless-custom-tls-cert-domain-mapping
-#
-# TODO: Add developer guide
-#
 # Knative Serving
 - Name: Knative Serving
   Dir: knative_serving
   Topics:
-    # Understanding serving
-  - Name: Understanding Knative Serving
-    File: serverless-understanding-serving
     # Knative services
   - Name: Serverless applications
     File: serverless-applications
   - Name: Traffic management
     File: serverless-traffic-management
-  - Name: Cluster logging with OpenShift Serverless
-    File: cluster-logging-serverless
-  # Tracing
-  - Name: Tracing requests using Jaeger
-    File: serverless-tracing
     # Routes
   - Name: Configuring routes for Knative services
     File: serverless-configuring-routes
-  - Name: Monitoring Knative services
-    File: serverless-service-monitoring
-  # Metrics
-  - Name: Metrics
-    File: serverless-serving-metrics
-#
 # Autoscaling
 - Name: Autoscaling
   Dir: autoscaling
@@ -3220,14 +3227,10 @@ Topics:
     File: serverless-autoscaling-concurrency
   - Name: Autoscaling dashboard
     File: serverless-autoscaling-dashboard
-#
 # Knative Eventing
 - Name: Knative Eventing
   Dir: knative_eventing
   Topics:
-# Understanding eventing
-  - Name: Understanding Knative Eventing
-    File: serverless-understanding-eventing
 # Event sinks
   - Name: Event sinks
     File: serverless-event-sinks
@@ -3271,7 +3274,6 @@ Topics:
     File: serverless-subs
   - Name: Configuring channel defaults
     File: serverless-configuring-channels
-#
 # Functions
 - Name: Functions
   Dir: functions
@@ -3308,7 +3310,6 @@ Topics:
   Topics:
   - Name: Using NVIDIA GPU resources with serverless applications
     File: gpu-resources
-#
 # CLI tools
 - Name: CLI tools
   Dir: cli_tools
diff --git a/modules/cluster-logging-about.adoc b/modules/cluster-logging-about.adoc
@@ -2,12 +2,11 @@
 //
 // * virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc
 // * logging/cluster-logging.adoc
-// * serverless/knative_serving/cluster-logging-serverless.adoc
+// * serverless/monitor/cluster-logging-serverless.adoc
 
 // This module uses conditionalized paragraphs so that the module
 // can be re-used in associated products.
 
-
 [id="cluster-logging-about_{context}"]
 = About deploying OpenShift Logging
 
diff --git a/modules/serverless-jaeger-config.adoc b/modules/serverless-jaeger-config.adoc
@@ -1,3 +1,7 @@
+// Module is included in the following assemblies:
+//
+// * serverless/monitor/serverless-tracing.adoc
+
 [id="serverless-jaeger-config_{context}"]
 = Configuring Jaeger for use with {ServerlessProductName}
 
@@ -22,6 +26,7 @@ metadata:
   name: jaeger
   namespace: default
 ----
+
 . Enable tracing for Knative Serving, by editing the `KnativeServing` CR and adding a YAML configuration for tracing:
 +
 .Tracing YAML example
@@ -63,4 +68,5 @@ $ oc get route jaeger
 NAME     HOST/PORT                         PATH   SERVICES       PORT    TERMINATION   WILDCARD
 jaeger   jaeger-default.apps.example.com          jaeger-query   <all>   reencrypt     None
 ----
+
 . Open the endpoint address in your browser to view the console.
diff --git a/modules/serverless-monitoring-services-configuration-scraping.adoc b/modules/serverless-monitoring-services-configuration-scraping.adoc
@@ -1,3 +1,7 @@
+// Module is included in the following assemblies:
+//
+// * serverless/monitor/serverless-service-monitoring.adoc
+
 [id="serverless-monitoring-services-configuration-scraping_{context}"]
 = Configuration for scraping custom metrics
 
diff --git a/modules/serverless-monitoring-services-custom-metrics.adoc b/modules/serverless-monitoring-services-custom-metrics.adoc
@@ -1,3 +1,7 @@
+// Module is included in the following assemblies:
+//
+// * serverless/monitor/serverless-service-monitoring.adoc
+
 [id="serverless-monitoring-services-custom-metrics_{context}"]
 = Knative service with custom application metrics
 
diff --git a/modules/serverless-monitoring-services-default-metrics.adoc b/modules/serverless-monitoring-services-default-metrics.adoc
@@ -1,3 +1,7 @@
+// Module is included in the following assemblies:
+//
+// * serverless/monitor/serverless-service-monitoring.adoc
+
 [id="serverless-monitoring-services-default-metrics_{context}"]
 = Knative service metrics exposed by default
 
diff --git a/modules/serverless-monitoring-services-examining-metrics-dashboard.adoc b/modules/serverless-monitoring-services-examining-metrics-dashboard.adoc
@@ -1,3 +1,7 @@
+// Module is included in the following assemblies:
+//
+// * serverless/monitor/serverless-service-monitoring.adoc
+
 [id="serverless-monitoring-services-examining-metrics-dashboard_{context}"]
 = Examining metrics of a service in the dashboard
 
diff --git a/modules/serverless-monitoring-services-examining-metrics.adoc b/modules/serverless-monitoring-services-examining-metrics.adoc
@@ -1,3 +1,7 @@
+// Module is included in the following assemblies:
+//
+// * serverless/monitor/serverless-service-monitoring.adoc
+
 [id="serverless-monitoring-services-examining-metrics_{context}"]
 = Examining metrics of a service
 
diff --git a/modules/serverless-queue-proxy-metrics.adoc b/modules/serverless-queue-proxy-metrics.adoc
@@ -1,3 +1,7 @@
+// Module is included in the following assemblies:
+//
+// * serverless/monitor/serverless-serving-metrics.adoc
+
 [id="serverless-queue-proxy-metrics_{context}"]
 = Queue proxy metrics
 
diff --git a/modules/serverless-using-cluster-logging-find-logs-knative-serving-components.adoc b/modules/serverless-using-cluster-logging-find-logs-knative-serving-components.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// serverless/cluster-logging-serverless.adoc
+// * serverless/monitor/cluster-logging-serverless.adoc
 
 [id="using-cluster-logging-to-find-logs-for-knative-serving-components_{context}"]
 = Using OpenShift Logging to find logs for Knative Serving components
@@ -13,8 +13,11 @@
 ----
 $ oc -n openshift-logging get route kibana
 ----
+
 . Use the route's URL to navigate to the Kibana dashboard and log in.
+
 . Check that the index is set to *.all*. If the index is not set to *.all*, only the {product-title} system logs will be listed.
+
 . Filter the logs by using the `knative-serving` namespace. Enter `kubernetes.namespace_name:knative-serving` in the search box to filter results.
 
 [NOTE]
diff --git a/modules/serverless-using-cluster-logging-find-logs-services-deployed.adoc b/modules/serverless-using-cluster-logging-find-logs-services-deployed.adoc
@@ -1,20 +1,25 @@
 // Module included in the following assemblies:
 //
-// serverless/cluster-logging-serverless.adoc
+// * serverless/monitor/cluster-logging-serverless.adoc
+
 [id="using-cluster-logging-to-find-logs-for-services-deployed-with-knative-serving_{context}"]
 = Using OpenShift Logging to find logs for services deployed with Knative Serving
 
 With OpenShift Logging, the logs that your applications write to the console are collected in Elasticsearch. The following procedure outlines how to apply these capabilities to applications deployed by using Knative Serving.
 
 .Procedure
+
 . Get the Kibana route:
 +
 [source,terminal]
 ----
 $ oc -n openshift-logging get route kibana
 ----
+
 . Use the route's URL to navigate to the Kibana dashboard and log in.
+
 . Check that the index is set to *.all*. If the index is not set to *.all*, only the OpenShift system logs will be listed.
+
 . Filter the logs by using the `knative-serving` namespace. Enter a filter for the service in the search box to filter results.
 +
 .Example filter
@@ -24,6 +29,7 @@ kubernetes.namespace_name:default AND kubernetes.labels.serving_knative_dev\/ser
 ----
 +
 You can also filter by using `/configuration` or `/revision`.
+
 . Narrow your search by using `kubernetes.container_name:<user_container>` to only display the logs generated by your application. Otherwise, you will see logs from the queue-proxy.
 
 [NOTE]
diff --git a/security/container_security/security-build.adoc b/security/container_security/security-build.adoc
@@ -33,6 +33,6 @@ include::modules/security-build-knative.adoc[leveloffset=+1]
 * xref:../../cicd/builds/creating-build-inputs.adoc#builds-input-secrets-configmaps_creating-build-inputs[Input secrets and config maps]
 ifndef::openshift-origin[]
 // **This section is being moved, update the link once content is in.* add link here[The CI/CD methodology and practice]
-* xref:../../serverless/knative_serving/serverless-understanding-serving.adoc#serverless-understanding-serving[Understanding Knative Serving]
+* xref:../../serverless/discover/serverless-understanding-serving.adoc#serverless-understanding-serving[Understanding Knative Serving]
 endif::[]
 * xref:../../applications/odc-viewing-application-composition-using-topology-view.adoc#odc-viewing-application-composition-using-topology-view[Viewing application composition using the Topology view]
diff --git a/serverless/discover/serverless-understanding-eventing.adoc b/serverless/discover/serverless-understanding-eventing.adoc
diff --git a/serverless/discover/serverless-understanding-serving.adoc b/serverless/discover/serverless-understanding-serving.adoc
diff --git a/serverless/knative_eventing/serverless-event-sinks.adoc b/serverless/knative_eventing/serverless-event-sinks.adoc
@@ -6,7 +6,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-A sink is an xref:../../serverless/knative_eventing/serverless-understanding-eventing.adoc#serverless-understanding-eventing-custom-resources[_Addressable_ custom resource (CR)] that can receive incoming events from other resources. Knative services, channels, and brokers are all examples of sinks.
+A sink is an xref:../../serverless/discover/serverless-understanding-eventing.adoc#serverless-understanding-eventing-custom-resources[_Addressable_ custom resource (CR)] that can receive incoming events from other resources. Knative services, channels, and brokers are all examples of sinks.
 
 [TIP]
 ====
diff --git a/serverless/monitor/cluster-logging-serverless.adoc b/serverless/monitor/cluster-logging-serverless.adoc
@@ -1,5 +1,6 @@
+include::modules/serverless-document-attributes.adoc[]
 [id="cluster-logging-serverless"]
-= Using OpenShift Logging
+= Using OpenShift Logging with {ServerlessProductName}
 include::modules/common-attributes.adoc[]
 :context: cluster-logging-serverless
 
diff --git a/serverless/monitor/images b/serverless/monitor/images
@@ -0,0 +1 @@
+../images
diff --git a/serverless/monitor/modules b/serverless/monitor/modules
@@ -0,0 +1 @@
+../modules
diff --git a/serverless/monitor/serverless-service-monitoring.adoc b/serverless/monitor/serverless-service-monitoring.adoc
@@ -21,17 +21,21 @@ Scraping the metrics does not affect autoscaling of a Knative service, because s
 .Additional resources
 
 * For more information on {product-title} monitoring stack, see xref:../../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Understanding the monitoring stack].
+
 * For information on monitoring the components of Serverless itself, as opposed to Knative services, see xref:../../serverless/admin_guide/serverless-admin-monitoring.adoc#serverless-admin-monitoring[Monitoring serverless components].
 
 include::modules/serverless-monitoring-services-default-metrics.adoc[leveloffset=+1]
+
 include::modules/serverless-monitoring-services-custom-metrics.adoc[leveloffset=+1]
 
 include::modules/serverless-monitoring-services-configuration-scraping.adoc[leveloffset=+1]
 
 .Additional resources
 
 * See also xref:../../monitoring/managing-metrics.adoc#specifying-how-a-service-is-monitored[Enabling monitoring for user-defined projects].
+
 * See also xref:../../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Specifying how a service is monitored].
 
 include::modules/serverless-monitoring-services-examining-metrics.adoc[leveloffset=+1]
+
 include::modules/serverless-monitoring-services-examining-metrics-dashboard.adoc[leveloffset=+1]
diff --git a/serverless/monitor/serverless-serving-metrics.adoc b/serverless/monitor/serverless-serving-metrics.adoc
@@ -17,7 +17,7 @@ Metrics enable developers to monitor how Knative services are performing.
 ====
 If Service Mesh is enabled with mTLS, metrics for Knative Serving are disabled by default because Service Mesh prevents Prometheus from scraping metrics.
 
-For information about resolving this issue, see xref:../../serverless/admin_guide/serverless-ossm-setup.html#serverless-ossm-enabling-serving-metrics_serverless-ossm-setup[Integrating Service Mesh with OpenShift Serverless].
+For information about resolving this issue, see xref:../../serverless/admin_guide/serverless-ossm-setup.adoc#serverless-ossm-enabling-serving-metrics_serverless-ossm-setup[Integrating Service Mesh with OpenShift Serverless].
 ====
 
 include::modules/serverless-queue-proxy-metrics.adoc[leveloffset=+1]
diff --git a/serverless/monitor/serverless-tracing.adoc b/serverless/monitor/serverless-tracing.adoc
diff --git a/serverless/serverless-getting-started.adoc b/serverless/serverless-getting-started.adoc
@@ -23,9 +23,3 @@ Developers on {ServerlessProductName} can use the provided Kubernetes native API
 == Supported configurations
 
 The set of supported features, configurations, and integrations for {ServerlessProductName}, current and past versions, are available at the link:https://access.redhat.com/articles/4912821[Supported Configurations page].
-
-[id="next-steps_serverless-getting-started"]
-== Next steps
-
-* Install the xref:../serverless/install/install-serverless-operator.adoc#install-serverless-operator[{ServerlessOperatorName}] on your {product-title} cluster to get started.
-* View the xref:../serverless/serverless-release-notes.adoc#serverless-release-notes[{ServerlessProductName} release notes].
diff --git a/serverless/update/upgrading-serverless.adoc b/serverless/update/upgrading-serverless.adoc
