From 2babcf50fdb89e8a90e65994bf78d21e63bc6b60 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Wed, 15 Dec 2021 09:32:08 -0600 Subject: [PATCH] Update docs structure --- _topic_maps/_topic_map.yml | 67 ++++++++++--------- modules/cluster-logging-about.adoc | 3 +- modules/serverless-jaeger-config.adoc | 6 ++ ...oring-services-configuration-scraping.adoc | 4 ++ ...ss-monitoring-services-custom-metrics.adoc | 4 ++ ...s-monitoring-services-default-metrics.adoc | 4 ++ ...-services-examining-metrics-dashboard.adoc | 4 ++ ...monitoring-services-examining-metrics.adoc | 4 ++ modules/serverless-queue-proxy-metrics.adoc | 4 ++ ...-find-logs-knative-serving-components.adoc | 5 +- ...r-logging-find-logs-services-deployed.adoc | 8 ++- .../container_security/security-build.adoc | 2 +- .../serverless-understanding-eventing.adoc | 0 .../serverless-understanding-serving.adoc | 0 .../serverless-event-sinks.adoc | 2 +- .../cluster-logging-serverless.adoc | 3 +- serverless/monitor/images | 1 + serverless/monitor/modules | 1 + .../serverless-service-monitoring.adoc | 4 ++ .../serverless-serving-metrics.adoc | 2 +- .../serverless-tracing.adoc | 0 serverless/serverless-getting-started.adoc | 6 -- .../upgrading-serverless.adoc | 0 23 files changed, 87 insertions(+), 47 deletions(-) rename serverless/{knative_eventing => discover}/serverless-understanding-eventing.adoc (100%) rename serverless/{knative_serving => discover}/serverless-understanding-serving.adoc (100%) rename serverless/{knative_serving => monitor}/cluster-logging-serverless.adoc (81%) create mode 120000 serverless/monitor/images create mode 120000 serverless/monitor/modules rename serverless/{knative_serving => monitor}/serverless-service-monitoring.adoc (99%) rename serverless/{knative_serving => monitor}/serverless-serving-metrics.adoc (92%) rename serverless/{knative_serving => monitor}/serverless-tracing.adoc (100%) rename serverless/{install => update}/upgrading-serverless.adoc (100%) diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index c86ca2529e..802ae7b96a 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -3109,16 +3109,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: @@ -3128,10 +3127,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 @@ -3169,35 +3193,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 @@ -3210,14 +3217,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 @@ -3261,7 +3264,6 @@ Topics: File: serverless-subs - Name: Configuring channel defaults File: serverless-configuring-channels -# # Functions - Name: Functions Dir: functions @@ -3298,7 +3300,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 index c1b9b9556d..62a1faebe4 100644 --- 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 index bae5b4d175..34b1eea529 100644 --- 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 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 index 852a0b2821..7a8ae81abb 100644 --- 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 index fad08f9b87..61a84a7029 100644 --- 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 index a193f0154f..8c4941f27c 100644 --- 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 index b9cb4988c4..988161f726 100644 --- 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 index c9e1365755..a1465369b8 100644 --- 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 index b897939ab6..27f8ea5bea 100644 --- 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 index 20236ff0fe..bfecd0d535 100644 --- 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 index f85a0922d6..7fbb530f02 100644 --- 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:` 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 index 0efd4a532d..83fb8c3143 100644 --- 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/knative_eventing/serverless-understanding-eventing.adoc b/serverless/discover/serverless-understanding-eventing.adoc similarity index 100% rename from serverless/knative_eventing/serverless-understanding-eventing.adoc rename to serverless/discover/serverless-understanding-eventing.adoc diff --git a/serverless/knative_serving/serverless-understanding-serving.adoc b/serverless/discover/serverless-understanding-serving.adoc similarity index 100% rename from serverless/knative_serving/serverless-understanding-serving.adoc rename to serverless/discover/serverless-understanding-serving.adoc diff --git a/serverless/knative_eventing/serverless-event-sinks.adoc b/serverless/knative_eventing/serverless-event-sinks.adoc index b103b7ecf1..da7624895f 100644 --- 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/knative_serving/cluster-logging-serverless.adoc b/serverless/monitor/cluster-logging-serverless.adoc similarity index 81% rename from serverless/knative_serving/cluster-logging-serverless.adoc rename to serverless/monitor/cluster-logging-serverless.adoc index a2d708eac1..7e0ab7b82c 100644 --- a/serverless/knative_serving/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 new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/serverless/monitor/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/serverless/monitor/modules b/serverless/monitor/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/serverless/monitor/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/serverless/knative_serving/serverless-service-monitoring.adoc b/serverless/monitor/serverless-service-monitoring.adoc similarity index 99% rename from serverless/knative_serving/serverless-service-monitoring.adoc rename to serverless/monitor/serverless-service-monitoring.adoc index 3436cb3385..d72665e21b 100644 --- a/serverless/knative_serving/serverless-service-monitoring.adoc +++ b/serverless/monitor/serverless-service-monitoring.adoc @@ -21,9 +21,11 @@ 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] @@ -31,7 +33,9 @@ include::modules/serverless-monitoring-services-configuration-scraping.adoc[leve .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/knative_serving/serverless-serving-metrics.adoc b/serverless/monitor/serverless-serving-metrics.adoc similarity index 92% rename from serverless/knative_serving/serverless-serving-metrics.adoc rename to serverless/monitor/serverless-serving-metrics.adoc index c4e352ec5e..fce5d70189 100644 --- a/serverless/knative_serving/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/knative_serving/serverless-tracing.adoc b/serverless/monitor/serverless-tracing.adoc similarity index 100% rename from serverless/knative_serving/serverless-tracing.adoc rename to serverless/monitor/serverless-tracing.adoc diff --git a/serverless/serverless-getting-started.adoc b/serverless/serverless-getting-started.adoc index 5c1d8e2eef..80dfc96b51 100644 --- 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/install/upgrading-serverless.adoc b/serverless/update/upgrading-serverless.adoc similarity index 100% rename from serverless/install/upgrading-serverless.adoc rename to serverless/update/upgrading-serverless.adoc