From f74c95ed3d8343d8edbbfb03da7dcd533a2e7c97 Mon Sep 17 00:00:00 2001 From: abrennan Date: Tue, 26 May 2020 15:14:44 -0500 Subject: [PATCH] [WIP] Create subscription docs for Serverless --- _topic_map.yml | 3 + .../serverless-creating-subscriptions.adoc | 60 +++++++++++++++++++ modules/serverless-inmemorychannel.adoc | 4 +- .../knative_eventing/serverless-channels.adoc | 3 +- .../serverless-subscriptions.adoc | 11 ++++ 5 files changed, 77 insertions(+), 4 deletions(-) create mode 100644 modules/serverless-creating-subscriptions.adoc create mode 100644 serverless/knative_eventing/serverless-subscriptions.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 473d60ccd9..a6ae9b7a9a 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2371,6 +2371,9 @@ Topics: # Channels - Name: Using channels File: serverless-channels +# Subscriptions + - Name: Using subscriptions to send events from a channel to a sink + File: serverless-subscriptions # Triggers - Name: Using triggers File: serverless-kn-trigger diff --git a/modules/serverless-creating-subscriptions.adoc b/modules/serverless-creating-subscriptions.adoc new file mode 100644 index 0000000000..adb653d9a5 --- /dev/null +++ b/modules/serverless-creating-subscriptions.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// +// * serverless/knative_eventing/serverless-subscriptions.adoc + +[id="serverless-creating-subscriptions_{context}"] += Creating a subscription + +You can create a subscription to connect a service or other event sink to a channel. + +[IMPORTANT] +==== +Knative Eventing is a Technology Preview feature. The InMemoryChannel type is provided for development use only, and should not be used in a production environment. +==== + +.Prerequisites + +* You must have a current installation of xref:../../serverless/installing_serverless/installing-openshift-serverless.adoc#serverless-install-web-console_installing-openshift-serverless[{ServerlessProductName}], including Knative Serving and Eventing, in your {product-title} cluster. This can be installed by a cluster administrator. +* If you do not have an existing sink that you wish to use, create a Service to use as a sink by following the documentation on xref:../../serverless/serving-creating-managing-apps.adoc#serving-creating-managing-apps[Creating and managing serverless applications]. +* You must have a channel to connect your subscription to. See xref:../../serverless/knative_eventing/serverless-channels.adoc#serverless-channels[Using channels with Knative Eventing]. + +.Procedure + +. Create a Subscription object to connect a channel to a service, by creating a YAML file containing the following: ++ +[source,yml] +---- +apiVersion: messaging.knative.dev/v1beta1 +kind: Subscription +metadata: + name: my-subscription <1> + namespace: default +spec: + channel: <2> + apiVersion: messaging.knative.dev/v1beta1 + kind: Channel + name: example-channel + delivery: <3> + deadLetterSink: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: error-handler + subscriber: <4> + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: event-display +---- ++ +<1> Name of the subscription. +<2> Configuration settings for the channel that the subscription connects to. +<3> Configuration settings for event delivery. This tells the subscription what happens to events that cannot be delivered to the subscriber. When this is configured, events that failed to be consumed are sent to the `deadLetterSink`. The event is dropped, no re-delivery of the event is attempted, and an error is logged in the system. The `deadLetterSink` value must be a link:https://pkg.go.dev/knative.dev/pkg/apis/duck/v1?tab=doc#Destination[Destination]. +<4> Configuration settings for the subscriber. This is the event sink that events are delivered to from the channel. + +. Apply the YAML file by entering: ++ +---- +$ oc apply -f +---- diff --git a/modules/serverless-inmemorychannel.adoc b/modules/serverless-inmemorychannel.adoc index 0f9f037f83..2157f1172c 100644 --- a/modules/serverless-inmemorychannel.adoc +++ b/modules/serverless-inmemorychannel.adoc @@ -11,8 +11,8 @@ The following are limitations of InMemoryChannel type channels: * No event persistence is available. If a Pod goes down, events on that Pod are lost. * InMemoryChannel type channels do not implement event ordering, so two events that are received in the channel at the same time can be delivered to a subscriber in any order. -* If a subscriber rejects an event, there are no re-delivery attempts. Instead, the rejected event is sent to a `deadLetterSink` if this sink exists, or is otherwise dropped. -// add link to subscription docs after rebase on top of this +* If a subscriber rejects an event, there are no re-delivery attempts. Instead, the rejected event is sent to a `deadLetterSink` if this sink exists, or is otherwise dropped. For more information about configuring event delivery and `deadLetterSink` settings for a channel, see xref:../../serverless/knative_eventing/serverless-subscriptions.adoc#serverless-subscriptions[Using subscriptions to send events from a channel to a sink]. + When you install Knative Eventing, the following custom resource definition (CRD) is created automatically: [source,yaml] diff --git a/serverless/knative_eventing/serverless-channels.adoc b/serverless/knative_eventing/serverless-channels.adoc index b4c9c47e31..32dd754bdd 100644 --- a/serverless/knative_eventing/serverless-channels.adoc +++ b/serverless/knative_eventing/serverless-channels.adoc @@ -7,7 +7,7 @@ include::modules/common-attributes.adoc[] toc::[] It is possible to sink events from an event source to a Knative Eventing channel. -Channels are Custom Resources (CRs) that define a single event-forwarding and persistence layer. +Channels are custom resources (CRs) that define a single event-forwarding and persistence layer. After events have been sent to a channel, these events can be sent to multiple Knative services by using a subscription. The default configuration for channel instances is defined in the `default-ch-webhook` ConfigMap. However, developers can still create their own channels directly by instantiating a supported channel object. @@ -17,4 +17,3 @@ The default configuration for channel instances is defined in the `default-ch-we Currently, {ServerlessProductName} only supports the use of InMemoryChannel type channels as part of the Knative Eventing Technology Preview. include::modules/serverless-inmemorychannel.adoc[leveloffset=+1] -// TODO: Add docs for Kafka channels; separate Jira issue diff --git a/serverless/knative_eventing/serverless-subscriptions.adoc b/serverless/knative_eventing/serverless-subscriptions.adoc new file mode 100644 index 0000000000..e4a1133d0a --- /dev/null +++ b/serverless/knative_eventing/serverless-subscriptions.adoc @@ -0,0 +1,11 @@ +include::modules/serverless-document-attributes.adoc[] +[id="serverless-subscriptions"] += Using subscriptions to send events from a channel to a sink +:context: serverless-subscriptions +include::modules/common-attributes.adoc[] + +toc::[] + +Subscriptions deliver events to event sinks from a Channel. + +include::modules/serverless-creating-subscriptions.adoc[leveloffset=+1]