Merge pull request #33595 from abrennan89/sinkdocs

SRVCLI-296 + SRVCOM-1245: Updating serving, eventing and sink doc structure

Author: abrennan89

_topic_map.yml

@@ -2925,8 +2925,7 @@ Topics:
 # Intro / getting started
 - Name: Getting started
   File: serverless-getting-started
-- Name: Installing the Knative CLI
-  File: installing-kn
+#
 # Admin guide
 - Name: Administration guide
   Dir: admin_guide
@@ -2954,24 +2953,19 @@ Topics:
     # Metering
   - Name: Using metering with OpenShift Serverless
     File: serverless-metering
-# Architecture
-- Name: Architecture
-  Dir: architecture
-  Topics:
-  - Name: Knative Serving
-    File: serverless-serving-architecture
-  - Name: Knative Eventing
-    File: serverless-event-architecture
-# HA
-- Name: High availability on OpenShift Serverless
-  File: serverless-HA
-# Tracing
-- Name: Tracing requests
-  File: serverless-tracing
+    # HA
+  - Name: High availability on OpenShift Serverless
+    File: serverless-ha
+#
+# 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
@@ -2982,10 +2976,20 @@ Topics:
     File: cluster-logging-serverless
   - Name: Splitting traffic between revisions
     File: splitting-traffic-between-revisions-knative
+  # Tracing
+  - Name: Tracing requests using Jaeger
+    File: serverless-tracing
+#
 # 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
 # Brokers
   - Name: Brokers
     File: serverless-using-brokers
@@ -3014,8 +3018,6 @@ Topics:
     File: serverless-sinkbinding
   - Name: Using a Kafka source
     File: serverless-kafka-source
-  - Name: Connecting event sources to sinks
-    File: srvls-connecting-source-sinks
 # Channels
 - Name: Channels
   Dir: channels
@@ -3026,11 +3028,10 @@ Topics:
     File: serverless-creating-channels
   - Name: Subscriptions
     File: serverless-subs
-  - Name: Connecting a channel to an event source
-    File: connect-channels-event-source
   - Name: Configuring channel defaults
     File: serverless-configuring-channels
-# Functions - uncomment at tech preview
+#
+# Functions
 - Name: Functions
   Dir: functions
   Topics:
@@ -3052,6 +3053,7 @@ Topics:
     File: serverless-functions-eventing
   - Name: Functions development reference guide
     File: serverless-functions-reference-guide
+#
 # Networking
 - Name: Networking
   Dir: networking
@@ -3068,17 +3070,21 @@ Topics:
     File: serverless-ossm-custom-domains
   - Name: Configuring TLS for a custom domain using Service Mesh
     File: serverless-ossm-tls
+#
 # Integrations
 - Name: Integrations
   Dir: integrations
   Topics:
   - Name: Using NVIDIA GPU resources with serverless applications
     File: gpu-resources
-# CLI reference guide
-- Name: CLI reference
-  Dir: cli_reference
+#
+# CLI tools
+- Name: CLI tools
+  Dir: cli_tools
   Topics:
-  - Name: Advanced kn configuration
+  - Name: Installing the Knative CLI
+    File: installing-kn
+  - Name: Knative CLI advanced configuration
     File: advanced-kn-config
   - Name: kn flags reference
     File: kn-flags-reference

cli_reference/kn-cli-tools.adoc

@@ -32,4 +32,4 @@ Key features of the `kn` CLI include:
 [id="kn-cli-tools-installing-kn"]
 == Installing the Knative CLI
 
-See xref:../serverless/installing-kn.adoc#installing-kn[Installing the Knative CLI].
+See xref:../serverless/cli_tools/installing-kn.adoc#installing-kn[Installing the Knative CLI].

modules/serverless-config-replicas.adoc

@@ -1,7 +1,3 @@
-// Module is included in the following assemblies:
-//
-// serverless/serverless-HA.adoc
-
 [id="serverless-config-replicas_{context}"]
 = Configuring high availability replicas on {ServerlessProductName}
 
@@ -11,6 +7,7 @@ You modify the number of replicas that are created per controller by changing th
 // This field also specifies the minimum number of _activators_ if you are using the horizontal pod autoscaler (HPA). For more information about HPA, see
 
 .Prerequisites
+
 * An {product-title} account with cluster administrator access.
 * Installed the {ServerlessOperatorName} and Knative Serving.
 

modules/serverless-connect-sink-source-odc.adoc

@@ -1,16 +1,8 @@
-// Module included in the following assemblies:
-//
-//  * serverless/channels/connect-channels-event-source.adoc
-// * serverless/event_sources/srvls-connecting-source-sinks.adoc
-
 [id="serverless-connect-sink-source-odc_{context}"]
 = Connect an event source to a sink using the Developer perspective
 
 You can create multiple event source types in {product-title} that can be connected to sinks.
 
-A sink is an addressable resource that can receive incoming events from other Knative Eventing resources. Knative services, channels, and brokers are all examples of sinks.
-// Add functions as services to the list for tech preview
-
 .Prerequisites
 
 To connect an event source to a sink using the *Developer* perspective, ensure that:

modules/serverless-connect-trigger-sink.adoc

@@ -0,0 +1,22 @@
+[id="serverless-connect-trigger-sink_{context}"]
+= Connecting a trigger to a sink
+
+You can connect a trigger to a sink, so that events from a broker are filtered before they are sent to the sink. A sink that is connected to a trigger is configured as a `subscriber` in the `Trigger` resource spec.
+
+.Example of a trigger connected to a Kafka sink
+[source,yaml]
+----
+apiVersion: eventing.knative.dev/v1
+kind: Trigger
+metadata:
+  name: <trigger_name> <1>
+spec:
+...
+  subscriber:
+    ref:
+      apiVersion: eventing.knative.dev/v1alpha1
+      kind: KafkaSink
+      name: <kafka_sink_name> <2>
+----
+<1> The name of the trigger being connected to the sink.
+<2> The name of a `KafkaSink` object.

modules/serverless-installing-cli-linux-ibm-power-rpm.adoc

@@ -1,7 +1,3 @@
-// Module included in the following assemblies:
-//
-// * serverless/installing-kn.adoc
-
 [id="installing-cli-linux-ibm-power-rpm_{context}"]
 = Installing the Knative CLI for Linux on IBM Power Systems using an RPM
 
@@ -15,14 +11,12 @@ For {op-system-base-full}, you can install the Knative CLI (`kn`) as an RPM if y
 ----
 # subscription-manager register
 ----
-
 . Refresh the RHSM:
 +
 [source,terminal]
 ----
 # subscription-manager refresh
 ----
-
 . Attach the subscription to a system by specifying ID of the subscription pool, using the `--pool` option:
 +
 [source,terminal]
@@ -31,14 +25,12 @@ For {op-system-base-full}, you can install the Knative CLI (`kn`) as an RPM if y
 ----
 +
 <1> Pool ID for an active {product-title} subscription
-
 . Enable the repository using Red Hat Subscription Manager:
 +
 [source,terminal]
 ----
 # subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-ppc64le-rpms"
 ----
-
 . Install the `openshift-serverless-clients` on the system:
 +
 [source,terminal]

modules/serverless-installing-cli-linux-ibm-power-tarball.adoc

@@ -1,7 +1,3 @@
-// Module included in the following assemblies:
-//
-// * serverless/installing-kn.adoc
-
 [id="installing-cli-linux-ibm-power-tarball_{context}"]
 = Installing the Knative CLI for Linux on IBM Power Systems
 
@@ -10,16 +6,13 @@ For Linux distributions, you can download the Knative CLI (`kn`) directly as a `
 .Procedure
 
 . Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-linux-ppc64le.tar.gz[`kn` CLI].
-
 . Unpack the archive:
 +
 [source,terminal]
 ----
 $ tar -xf <file>
 ----
-
 . Move the `kn` binary to a directory on your `PATH`.
-
 . To check your `PATH`, run:
 +
 [source,terminal]

modules/serverless-installing-cli-linux-ibm-z-rpm.adoc

@@ -1,7 +1,3 @@
-// Module included in the following assemblies:
-//
-// * serverless/installing-kn.adoc
-
 [id="installing-cli-linux-ibm-z-rpm_{context}"]
 = Installing the Knative CLI for Linux on IBM Z and LinuxONE using an RPM
 
@@ -15,14 +11,12 @@ For {op-system-base-full}, you can install the Knative CLI (`kn`) as an RPM if y
 ----
 # subscription-manager register
 ----
-
 . Refresh the RHSM:
 +
 [source,terminal]
 ----
 # subscription-manager refresh
 ----
-
 . Attach the subscription to a system by specifying ID of the subscription pool, using the `--pool` option:
 +
 [source,terminal]
@@ -31,14 +25,12 @@ For {op-system-base-full}, you can install the Knative CLI (`kn`) as an RPM if y
 ----
 +
 <1> Pool ID for an active {product-title} subscription
-
 . Enable the repository using Red Hat Subscription Manager:
 +
 [source,terminal]
 ----
 # subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-s390x-rpms"
 ----
-
 . Install the `openshift-serverless-clients` on the system:
 +
 [source,terminal]

modules/serverless-installing-cli-linux-ibm-z-tarball.adoc

@@ -1,7 +1,3 @@
-// Module included in the following assemblies:
-//
-// * serverless/installing-kn.adoc
-
 [id="installing-cli-linux-ibm-z-tarball_{context}"]
 = Installing the Knative CLI for Linux on IBM Z and LinuxONE
 
@@ -10,23 +6,19 @@ For Linux distributions, you can download the Knative CLI (`kn`)  directly as a
 .Procedure
 
 . Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest/kn-linux-s390x.tar.gz[`kn` CLI].
-
 . Unpack the archive:
 +
 [source,terminal]
 ----
 $ tar -xf <file>
 ----
-
 . Move the `kn` binary to a directory on your `PATH`.
-
 . To check your `PATH`, run:
 +
 [source,terminal]
 ----
 $ echo $PATH
 ----
-
 +
 [NOTE]
 ====

modules/serverless-installing-cli-linux-rpm.adoc

@@ -1,51 +1,38 @@
-// Module is included in the following assemblies:
-//
-// serverless/knative-client.adoc
-
 [id="installing-cli-linux-rpm_{context}"]
 = Installing the Knative CLI for Linux using an RPM
 
 For {op-system-base-full}, you can install the Knative CLI (`kn`) as an RPM if you have an active {product-title} subscription on your Red Hat account.
 
-
 .Procedure
+
 . Enter the command:
 +
-
 [source,terminal]
 ----
 # subscription-manager register
 ----
-
 . Enter the command:
 +
-
 [source,terminal]
 ----
 # subscription-manager refresh
 ----
-
 . Enter the command:
 +
-
 [source,terminal]
 ----
 # subscription-manager attach --pool=<pool_id> <1>
 ----
 +
 <1> Pool ID for an active {product-title} subscription
-
 . Enter the command:
 +
-
 [source,terminal]
 ----
 # subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-x86_64-rpms"
 ----
-
 . Enter the command:
 +
-
 [source,terminal]
 ----
 # yum install openshift-serverless-clients