From 414aeee1db3ad703e7fee655dc8e6ea41f1f8d57 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Fri, 8 Apr 2022 11:46:06 -0500 Subject: [PATCH] SRCOM-1728: Updated channel and subs abstracts, introduction content --- _topic_maps/_topic_map.yml | 2 +- _topic_maps/_topic_map_osd.yml | 2 +- modules/serverless-create-channel-kn.adoc | 6 +++--- modules/serverless-create-channel-odc.adoc | 2 +- modules/serverless-create-default-channel-yaml.adoc | 4 ++-- modules/serverless-create-kafka-channel-yaml.adoc | 4 ++-- modules/serverless-creating-subscriptions-kn.adoc | 6 +++--- modules/serverless-creating-subscriptions-odc.adoc | 2 +- modules/serverless-creating-subscriptions-yaml.adoc | 4 ++-- modules/serverless-describe-subs-kn.adoc | 4 ++-- modules/serverless-list-subs-kn.adoc | 4 ++-- .../serverless-subscription-event-delivery-config.adoc | 2 +- modules/serverless-update-subscriptions-kn.adoc | 4 ++-- serverless/develop/serverless-creating-channels.adoc | 2 +- serverless/develop/serverless-subs.adoc | 4 ++-- serverless/discover/serverless-channels.adoc | 6 +----- snippets/serverless-channels-intro.adoc | 10 ++++++++++ 17 files changed, 37 insertions(+), 31 deletions(-) create mode 100644 snippets/serverless-channels-intro.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 009eea3d5b..5430507811 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -3405,7 +3405,7 @@ Topics: Name: Custom event sources - Name: Creating channels File: serverless-creating-channels - - Name: Creating subscriptions + - Name: Creating and managing subscriptions File: serverless-subs # Brokers - Name: Brokers diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml index feb9b5fcd4..1929fdb4ae 100644 --- a/_topic_maps/_topic_map_osd.yml +++ b/_topic_maps/_topic_map_osd.yml @@ -264,7 +264,7 @@ Topics: Name: Custom event sources - Name: Creating channels File: serverless-creating-channels - - Name: Creating subscriptions + - Name: Creating and managing subscriptions File: serverless-subs - Name: Brokers File: serverless-using-brokers diff --git a/modules/serverless-create-channel-kn.adoc b/modules/serverless-create-channel-kn.adoc index 2c654c6516..dfa28da811 100644 --- a/modules/serverless-create-channel-kn.adoc +++ b/modules/serverless-create-channel-kn.adoc @@ -6,12 +6,12 @@ [id="serverless-create-channel-kn_{context}"] = Creating a channel by using the Knative CLI -You can create a channel with the cluster default configuration by using the `kn` CLI. +Using the `kn` CLI to create channels provides a more streamlined and intuitive user interface than modifying YAML files directly. You can use the `kn channel create` command to create a channel by using the `kn` CLI. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure @@ -55,7 +55,7 @@ mychannel InMemoryChannel http://mychannel-kn-channel.default.svc.cluster.lo ---- .Deleting a channel - +// split into own module, out of scope for this PR * Delete a channel: + [source,terminal] diff --git a/modules/serverless-create-channel-odc.adoc b/modules/serverless-create-channel-odc.adoc index ae9abea1c0..6b27f2bd4c 100644 --- a/modules/serverless-create-channel-odc.adoc +++ b/modules/serverless-create-channel-odc.adoc @@ -6,7 +6,7 @@ [id="serverless-create-channel-odc_{context}"] = Creating a channel by using the web console -You can create a channel by using the {product-title} web console. +Using the {product-title} web console provides a streamlined and intuitive user interface to create a channel. After Knative Eventing is installed on your cluster, you can create a channel by using the web console. .Prerequisites diff --git a/modules/serverless-create-default-channel-yaml.adoc b/modules/serverless-create-default-channel-yaml.adoc index 09fe6679ea..ba56ed9c9e 100644 --- a/modules/serverless-create-default-channel-yaml.adoc +++ b/modules/serverless-create-default-channel-yaml.adoc @@ -6,12 +6,12 @@ [id="serverless-create-default-channel-yaml_{context}"] = Creating a default implementation channel by using YAML -You can create a channel with the cluster default configuration by using YAML. +Creating Knative resources by using YAML files uses a declarative API, which enables you to describe channels declaratively and in a reproducible manner. To create a serverless channel by using YAML, you must create a YAML file that defines a `Channel` object, then apply it by using the `oc apply` command. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster. -* Install the OpenShift CLI (`oc`). +* Install the OpenShift (`oc`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure diff --git a/modules/serverless-create-kafka-channel-yaml.adoc b/modules/serverless-create-kafka-channel-yaml.adoc index 286c65419f..392dcb5b8f 100644 --- a/modules/serverless-create-kafka-channel-yaml.adoc +++ b/modules/serverless-create-kafka-channel-yaml.adoc @@ -7,12 +7,12 @@ [id="serverless-create-kafka-channel-yaml_{context}"] = Creating a Kafka channel by using YAML -You can create a Knative Eventing channel that is backed by Kafka topics. To do this, you must create a `KafkaChannel` object. The following procedure explains how you can create a `KafkaChannel` object by using YAML files and the `oc` CLI. +Creating Knative resources by using YAML files uses a declarative API, which enables you to describe channels declaratively and in a reproducible manner. You can create a Knative Eventing channel that is backed by Kafka topics by creating a Kafka channel. To create a Kafka channel by using YAML, you must create a YAML file that defines a `KafkaChannel` object, then apply it by using the `oc apply` command. .Prerequisites * The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your {product-title} cluster. -* Install the OpenShift CLI (`oc`). +* Install the OpenShift (`oc`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure diff --git a/modules/serverless-creating-subscriptions-kn.adoc b/modules/serverless-creating-subscriptions-kn.adoc index ad989ce495..a783bb7685 100644 --- a/modules/serverless-creating-subscriptions-kn.adoc +++ b/modules/serverless-creating-subscriptions-kn.adoc @@ -6,12 +6,12 @@ [id="serverless-creating-subscriptions-kn_{context}"] = Creating a subscription by using the Knative CLI -You can create a subscription to connect a channel to a sink by using the `kn` CLI. +After you have created a channel and an event sink, you can create a subscription to enable event delivery. Using the `kn` CLI to create subscriptions provides a more streamlined and intuitive user interface than modifying YAML files directly. You can use the `kn subscription create` command as well as the appropriate flags to create a subscription by using the `kn` CLI. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure @@ -61,7 +61,7 @@ mysubscription Channel:mychannel ksvc:event-display ---- .Deleting a subscription - +// move to own procedure, out of scope for this PR * Delete a subscription: + [source,terminal] diff --git a/modules/serverless-creating-subscriptions-odc.adoc b/modules/serverless-creating-subscriptions-odc.adoc index a96dea0399..310c1d9549 100644 --- a/modules/serverless-creating-subscriptions-odc.adoc +++ b/modules/serverless-creating-subscriptions-odc.adoc @@ -6,7 +6,7 @@ [id="serverless-creating-subscriptions-odc_{context}"] = Creating a subscription by using the web console -You can create a subscription to connect a channel to a sink by using the {product-title} web console. +After you have created a channel and an event sink, you can create a subscription to enable event delivery. Using the {product-title} web console provides a streamlined and intuitive user interface to create a subscription. .Prerequisites diff --git a/modules/serverless-creating-subscriptions-yaml.adoc b/modules/serverless-creating-subscriptions-yaml.adoc index f0cce07c69..40cef67eaa 100644 --- a/modules/serverless-creating-subscriptions-yaml.adoc +++ b/modules/serverless-creating-subscriptions-yaml.adoc @@ -6,12 +6,12 @@ [id="serverless-creating-subscriptions-yaml_{context}"] = Creating a subscription by using YAML -You can create a subscription to connect a channel to a sink by using YAML. +After you have created a channel and an event sink, you can create a subscription to enable event delivery. Creating Knative resources by using YAML files uses a declarative API, which enables you to describe subscriptions declaratively and in a reproducible manner. To create a subscription by using YAML, you must create a YAML file that defines a `Subscription` object, then apply it by using the `oc apply` command. .Prerequisites * The {ServerlessOperatorName} and Knative Eventing are installed on the cluster. -* Install the OpenShift CLI (`oc`). +* Install the OpenShift (`oc`) CLI. * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. .Procedure diff --git a/modules/serverless-describe-subs-kn.adoc b/modules/serverless-describe-subs-kn.adoc index b5349533cf..a25682b39f 100644 --- a/modules/serverless-describe-subs-kn.adoc +++ b/modules/serverless-describe-subs-kn.adoc @@ -6,11 +6,11 @@ [id="serverless-describe-subs-kn_{context}"] = Describing subscriptions by using the Knative CLI -You can print information about a subscription in the terminal by using the `kn` CLI. +You can use the `kn subscription describe` command to print information about a subscription in the terminal by using the `kn` CLI. Using the `kn` CLI to describe subscriptions provides a more streamlined and intuitive user interface than viewing YAML files directly. .Prerequisites -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a subscription in your cluster. .Procedure diff --git a/modules/serverless-list-subs-kn.adoc b/modules/serverless-list-subs-kn.adoc index ceca85e02f..480db9a4b8 100644 --- a/modules/serverless-list-subs-kn.adoc +++ b/modules/serverless-list-subs-kn.adoc @@ -6,11 +6,11 @@ [id="serverless-list-subs-kn_{context}"] = Listing subscriptions by using the Knative CLI -You can list existing subscriptions on your cluster by using the `kn` CLI. +You can use the `kn subscription list` command to list existing subscriptions on your cluster by using the `kn` CLI. Using the `kn` CLI to list subscriptions provides a streamlined and intuitive user interface. .Prerequisites -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. .Procedure diff --git a/modules/serverless-subscription-event-delivery-config.adoc b/modules/serverless-subscription-event-delivery-config.adoc index 4585b3683b..b748e851e0 100644 --- a/modules/serverless-subscription-event-delivery-config.adoc +++ b/modules/serverless-subscription-event-delivery-config.adoc @@ -7,7 +7,7 @@ [id="serverless-subscription-event-delivery-config_{context}"] = Configuring event delivery failure parameters using subscriptions -Knative Eventing provides configuration parameters for subscriptions that can be used to control what happens to events in cases where events fail to be delivered. You can configure event delivery parameters for individual subscriptions by modifying the `delivery` settings for a `Subscription` object. +After you have created a channel and an event sink, you can create a subscription to enable event delivery. You can configure event delivery parameters for individual subscriptions by modifying the `delivery` settings for a `Subscription` object. Knative Eventing provides configuration parameters for subscriptions that you can use to control what happens to events in cases where events fail to be delivered. .Example `Subscription` object [source,yaml] diff --git a/modules/serverless-update-subscriptions-kn.adoc b/modules/serverless-update-subscriptions-kn.adoc index 7a86ba1fbd..e1055f77f7 100644 --- a/modules/serverless-update-subscriptions-kn.adoc +++ b/modules/serverless-update-subscriptions-kn.adoc @@ -6,11 +6,11 @@ [id="serverless-update-subscriptions-kn_{context}"] = Updating subscriptions by using the Knative CLI -You can update a subscription by using the `kn` CLI. +You can use the `kn subscription update` command as well as the appropriate flags to update a subscription from the terminal by using the `kn` CLI. Using the `kn` CLI to update subscriptions provides a more streamlined and intuitive user interface than updating YAML files directly. .Prerequisites -* You have installed the `kn` CLI. +* You have installed the Knative (`kn`) CLI. * You have created a subscription. .Procedure diff --git a/serverless/develop/serverless-creating-channels.adoc b/serverless/develop/serverless-creating-channels.adoc index d8920e4075..48cd6a69e0 100644 --- a/serverless/develop/serverless-creating-channels.adoc +++ b/serverless/develop/serverless-creating-channels.adoc @@ -6,7 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] -You can use the following procedures to create channels. +include::snippets/serverless-channels-intro.adoc[] include::modules/serverless-create-channel-odc.adoc[leveloffset=+1] include::modules/serverless-create-channel-kn.adoc[leveloffset=+1] diff --git a/serverless/develop/serverless-subs.adoc b/serverless/develop/serverless-subs.adoc index 19e31cc6b5..066c0f69b8 100644 --- a/serverless/develop/serverless-subs.adoc +++ b/serverless/develop/serverless-subs.adoc @@ -1,12 +1,12 @@ :_content-type: ASSEMBLY [id="serverless-subs"] -= Creating subscriptions += Creating and managing subscriptions include::_attributes/common-attributes.adoc[] :context: serverless-subs toc::[] -You can use the following procedures to create subscriptions that allow event sinks to subscribe to channels and receive events. +After you have created a channel and an event sink, you can create a subscription to enable event delivery. Subscriptions are created by configuring a `Subscription` object, which specifies the channel and the sink (also known as a _subscriber_) to deliver events to. You can also specify some sink-specific options, such as how to handle failures. include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+1] include::modules/serverless-creating-subscriptions-yaml.adoc[leveloffset=+1] diff --git a/serverless/discover/serverless-channels.adoc b/serverless/discover/serverless-channels.adoc index 66862a6001..4418c8299b 100644 --- a/serverless/discover/serverless-channels.adoc +++ b/serverless/discover/serverless-channels.adoc @@ -6,11 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] -Channels are custom resources that define a single event-forwarding and persistence layer. After events have been sent to a channel from an event source or producer, these events can be sent to multiple Knative services, or other sinks, by using a subscription. - -image::serverless-event-channel-workflow.png[Channel workflow overview] - -You can create channels by instantiating a supported `Channel` object, and configure xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-event-delivery[re-delivery attempts] by modifying the `delivery` spec in a `Subscription` object. +include::snippets/serverless-channels-intro.adoc[] After you create a `Channel` object, a mutating admission webhook adds a set of `spec.channelTemplate` properties for the `Channel` object based on the default channel implementation. For example, for an `InMemoryChannel` default implementation, the `Channel` object looks as follows: diff --git a/snippets/serverless-channels-intro.adoc b/snippets/serverless-channels-intro.adoc new file mode 100644 index 0000000000..63720d3c1f --- /dev/null +++ b/snippets/serverless-channels-intro.adoc @@ -0,0 +1,10 @@ +// Text snippet included in the following files +// +// * /serverless/develop/serverless-creating-channels.adoc +// * /serverless/discover/serverless-channels.adoc + +Channels are custom resources that define a single event-forwarding and persistence layer. After events have been sent to a channel from an event source or producer, these events can be sent to multiple Knative services or other sinks by using a subscription. + +image::serverless-event-channel-workflow.png[Channel workflow overview] + +You can create channels by instantiating a supported `Channel` object, and configure xref:../../serverless/develop/serverless-event-delivery.adoc#serverless-event-delivery[re-delivery attempts] by modifying the `delivery` spec in a `Subscription` object.