From 9750c70287721d8e50a2393b6086fcf309dcf97d Mon Sep 17 00:00:00 2001 From: abrennan Date: Wed, 15 Apr 2020 15:42:37 -0500 Subject: [PATCH] Documenting use of channels with Serverless --- _topic_map.yml | 69 ++++++++++--------- .../serverless-create-default-channel.adoc | 42 +++++++++++ modules/serverless-eventing-components.adoc | 64 ----------------- .../knative_eventing/serverless-channels.adoc | 26 +++++++ .../serverless-kn-source.adoc | 6 +- .../serverless-kn-trigger.adoc | 3 +- .../serverless-knative-eventing.adoc | 26 +++++-- serverless/serverless-config-HA.adoc | 2 +- 8 files changed, 127 insertions(+), 111 deletions(-) create mode 100644 modules/serverless-create-default-channel.adoc delete mode 100644 modules/serverless-eventing-components.adoc create mode 100644 serverless/knative_eventing/serverless-channels.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 8bc7258024..5917a16f35 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -1593,13 +1593,13 @@ Name: Serverless applications Dir: serverless Distros: openshift-enterprise,openshift-webscale Topics: -### Release notes +# Release notes - Name: Release Notes File: serverless-release-notes -### Intro / getting started +# Intro / getting started - Name: Getting started with OpenShift Serverless File: serverless-getting-started -### Installing OpenShift Serverless +# Installing OpenShift Serverless - Name: Installing OpenShift Serverless Dir: installing_serverless Topics: @@ -1609,19 +1609,19 @@ Topics: File: upgrading-serverless - Name: Installing Knative Serving File: installing-knative-serving -### - Name: Installing Knative Eventing -### File: installing-knative-eventing +# - Name: Installing Knative Eventing +# File: installing-knative-eventing - Name: Installing the Knative CLI File: installing-kn - Name: Removing OpenShift Serverless File: removing-openshift-serverless -### Knative CLI +# Knative CLI - Name: Knative CLI Dir: knative_cli Topics: - Name: Getting started with Knative CLI File: knative-cli -### Knative Serving +# Knative Serving - Name: Knative Serving Dir: knative_serving Topics: @@ -1639,34 +1639,37 @@ Topics: File: cluster-logging-serverless - Name: Splitting traffic between revisions File: splitting-traffic-between-revisions -### Knative Eventing -### - Name: Knative Eventing -### Dir: knative_eventing -### Topics: -### - Name: How Knative Eventing works -### File: serverless-knative-eventing -### Event sources -### - Name: Using the kn CLI to list event sources and event source types -### File: serverless-kn-source -### - Name: Using ApiServerSource -### File: serverless-apiserversource -### - Name: Using PingSource -### File: serverless-pingsource -### - Name: Using SinkBinding -### File: serverless-sinkbinding -### Triggers -### - Name: Using triggers with Knative Eventing -### File: serverless-kn-trigger -### Brokers -### - Name: Using the broker -### File: serverless-using-brokers -### HA -### - Name: Configuring high availability components -### File: serverless-config-HA -### Monitoring +# Knative Eventing +# - Name: Knative Eventing +# Dir: knative_eventing +# Topics: +# - Name: How Knative Eventing works +# File: serverless-knative-eventing +# Event sources +# - Name: Using the kn CLI to list event sources and event source types +# File: serverless-kn-source +# - Name: Using ApiServerSource +# File: serverless-apiserversource +# - Name: Using PingSource +# File: serverless-pingsource +# - Name: Using SinkBinding +# File: serverless-sinkbinding +# Triggers +# - Name: Using triggers +# File: serverless-kn-trigger +# Brokers +# - Name: Using the broker +# File: serverless-using-brokers +# Channels +# - Name: Using channels +# File: serverless-channels +# HA +# - Name: Configuring high-availability components +# File: serverless-config-HA +# Monitoring - Name: Monitoring OpenShift Serverless components File: monitoring-serverless -### Metering +# Metering - Name: Using metering with OpenShift Serverless File: serverless-metering #--- diff --git a/modules/serverless-create-default-channel.adoc b/modules/serverless-create-default-channel.adoc new file mode 100644 index 0000000000..4d7baec091 --- /dev/null +++ b/modules/serverless-create-default-channel.adoc @@ -0,0 +1,42 @@ +// Module is included in the following assemblies: +// +// serverless/knative_eventing/serverless-channels.adoc + +[id="serverless-create-default-channel_{context}"] += Creating a channel with cluster default configuration + +To create a channel using the cluster default configuration set by the cluster administrator, you must create a generic `Channel` custom object. + +.Example `Channel` object +[source,yaml] +---- +apiVersion: messaging.knative.dev/v1beta1 +kind: Channel +metadata: + name: example-channel + namespace: default +---- + +When the above `Channel` object is created, a mutating admission webhook adds a set of `spec.channelTemplate` properties for the `Channel` object based on the default channel implementation chosen by the cluster administrator. + +.Example `Channel` object with `spec.channelTemplate` properties +[source,yaml] +---- +apiVersion: messaging.knative.dev/v1beta1 +kind: Channel +metadata: + name: example-channel + namespace: default +spec: + channelTemplate: + apiVersion: messaging.knative.dev/v1beta1 + kind: InMemoryChannel +---- + +The channel controller will then create the backing channel instance based on that `spec.channelTemplate` configuration. The `spec.channelTemplate` properties cannot be changed after creation, because they are set by the default channel mechanism rather than by the user. + +When this mechanism is used, two objects are created, a generic channel, and an InMemoryChannel channel. + +The generic channel acts as a proxy that copies its subscriptions to the InMemoryChannel, and sets its status to reflect the status of the backing InMemoryChannel channel. + +Because the channel in this example is created in the default namespace, the channel uses the cluster default, which is InMemoryChannel. diff --git a/modules/serverless-eventing-components.adoc b/modules/serverless-eventing-components.adoc deleted file mode 100644 index bb6b485e16..0000000000 --- a/modules/serverless-eventing-components.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless-knative-eventing.adoc - -[id="serverless-eventing-components_{context}"] -= Knative Eventing components - -Event source:: Event sources are Kubernetes custom resources that provide a mechanism for registering interest in a class of events from an event producer. - -// Add 'Channel' / 'Sinks / consumers' - -Broker:: A broker represents an event mesh. Events are sent to the broker's ingress and are then sent to any event consumers that are subscribed to that broker. -After the event is in the broker, metadata for the event is stripped away so that there is no information about how the event entered the broker. -+ -.Example broker YAML definition ----- -apiVersion: eventing.knative.dev/v1alpha1 -kind: Broker -metadata: - name: default <1> -spec: - channelTemplateSpec: <2> - apiVersion: messaging.knative.dev/v1alpha1 - kind: InMemoryChannel ----- - -<1> The `default` broker is provided with your {ServerlessProductName} Knative Eventing installation. -<2> Event channels can be specified in the `channelTemplateSpec`. - -// NOTE: this is being replaced. Update when details are available upstream. - - -Trigger:: A trigger enables a Knative service to subscribe to events from a specific broker. -+ -.Example trigger YAML definition ----- -apiVersion: eventing.knative.dev/v1alpha1 -kind: Trigger -metadata: - name: my-service-trigger <1> -spec: - broker: default <2> - subscriber: <3> - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: my-service ----- - -<1> The name of the trigger. -<2> Specifies the name of the broker that the trigger will listen for events from. -<3> The `subscriber` section defines the Knative service that the broker sends events to. - -// == Next steps - -// * Install Knative Eventing -// * Using event sources -// * Using brokers -// * Using channels -// * Using triggers -// add links: * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -// * Install the Kafka event source -// * Install the Camel K event source -// * Integrate your AMQ Streams deployment with Knative Eventing using {ServerlessProductName}. diff --git a/serverless/knative_eventing/serverless-channels.adoc b/serverless/knative_eventing/serverless-channels.adoc new file mode 100644 index 0000000000..737c9eca55 --- /dev/null +++ b/serverless/knative_eventing/serverless-channels.adoc @@ -0,0 +1,26 @@ +include::modules/serverless-document-attributes.adoc[] +[id="serverless-channels"] += Using channels +include::modules/common-attributes.adoc[] +:context: serverless-channels + +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. +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. + +== Supported channel types +Currently, {ServerlessProductName} only supports the use of InMemoryChannel channels as part of the Knative Eventing Technology Preview. + +The following are limitations of InMemoryChannel channels: + +* No event persistence is available. If a Pod is goes down, events on that Pod will be lost. +* InMemoryChannel channels do not implement event ordering, so two events that are received in the channel at the same time may be delivered to a subscriber in any order. +* If a subscriber rejects an event, there are no redelivery attempts. Instead, the rejected event will be sent to a _dead letter sink_ if this exists, or is otherwise dropped. + +// TODO: Add link for dead letter sink docs once these are added. + +include::modules/serverless-create-default-channel.adoc[leveloffset=+1] diff --git a/serverless/knative_eventing/serverless-kn-source.adoc b/serverless/knative_eventing/serverless-kn-source.adoc index 859469f1c9..ff6851e710 100644 --- a/serverless/knative_eventing/serverless-kn-source.adoc +++ b/serverless/knative_eventing/serverless-kn-source.adoc @@ -10,9 +10,8 @@ You can use the `kn` CLI to list and manage available event sources or event sou Currently, `kn` supports management of the following event source types: -`ApiServerSource`:: Connects a sink to the Kubernetes API server. -`PingSource`:: Periodically sends ping events with a constant payload. It can be used as a timer. -`SinkBinding`:: Connects core Kubernetes resources like `Deployment`, `Job`, or `StatefulSet` with a sink. +ApiServerSource:: Connects a sink to the Kubernetes API server. +PingSource:: Periodically sends ping events with a constant payload. It can be used as a timer. // Additional sources can be added by the cluster administrator. For example, {ServerlessProductName} can be used with Kafka and Camel K event sources, which are installed using the Operator Hub in the {product-title} web console. // For more information about adding event source types as a cluster administrator, see @@ -24,4 +23,3 @@ include::modules/serverless-list-source.adoc[leveloffset=+1] .Next steps * See the documentation on xref:../knative_eventing/serverless-apiserversource.adoc#serverless-apiserversource[Using ApiServerSource]. * See the documentation on xref:../knative_eventing/serverless-pingsource.adoc#serverless-pingsource[Using PingSource]. -* See the documentation on xref:../knative_eventing/serverless-sinkbinding.adoc#serverless-sinkbinding[Using SinkBinding]. diff --git a/serverless/knative_eventing/serverless-kn-trigger.adoc b/serverless/knative_eventing/serverless-kn-trigger.adoc index 6aa18a817d..ca98c7f4e8 100644 --- a/serverless/knative_eventing/serverless-kn-trigger.adoc +++ b/serverless/knative_eventing/serverless-kn-trigger.adoc @@ -1,10 +1,9 @@ include::modules/serverless-document-attributes.adoc[] [id="serverless-kn-trigger"] -= Using triggers with Knative Eventing += Using triggers :context: serverless-kn-trigger include::modules/common-attributes.adoc[] - toc::[] All events which are sent to a channel or broker will be sent to all subscribers of that channel or broker by default. diff --git a/serverless/knative_eventing/serverless-knative-eventing.adoc b/serverless/knative_eventing/serverless-knative-eventing.adoc index 46ff52f7fc..b0faea7449 100644 --- a/serverless/knative_eventing/serverless-knative-eventing.adoc +++ b/serverless/knative_eventing/serverless-knative-eventing.adoc @@ -12,12 +12,24 @@ Event-driven architecture is based on the concept of decoupled relationships bet For more information about event-driven architecture, see link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[What is event-driven architecture?] -In a Knative Eventing workflow, event producers send information to an event source about changes to system state. -Examples of event producers include a Kafka cluster or the Kubernetes API server. -An event source is a resource object, which is the link between an event producer and a sink (or consumer) that receives those events. -Examples of sinks are Knative services and channels. -Events can also be sent to a broker, where they can be filtered using triggers before being sent to an event sink. +== Knative Eventing workflows -Using the broker and trigger together enables an event delivery mechanism that hides the details of event routing from the event producer and event consumer. +In a Knative Eventing workflow, _event producers_ send information to an event source about changes to system state. Examples of event producers include a Kafka cluster or the Kubernetes API server. -include::modules/serverless-eventing-components.adoc[leveloffset=+1] +An _event source_ is a resource object, which is the link between an event producer and a _sink_ (or consumer) that receives those events. Currently, {ServerlessProductName} supports the following event source types: + +ApiServerSource:: Connects a sink to the Kubernetes API server. +PingSource:: Periodically sends ping events with a constant payload. It can be used as a timer. + +SinkBinding is also supported, which allows you to connect core Kubernetes resources such as `Deployment`, `Job`, or `StatefulSet` with a sink. + +Examples of sinks are Knative services and channels. Events can also be sent to: + +* A _broker_, where they can be filtered using _triggers_ before being sent to a sink. Using the broker and trigger together enables an event delivery mechanism that hides the details of event routing from the event producer and event consumer. +* A _channel_, where Knative services can "subscribe" to receive events of a certain type. + +== Additional resources + +* For more information about brokers, see xref:../serverless-using-brokers.adoc#serverless-using-brokers[Using brokers]. +* For more information about triggers, see xref:../serverless-kn-trigger.adoc#serverless-kn-trigger[Using triggers]. +* For more information about channels, see xref:../serverless-channels.adoc#serverless-channels[Using channels]. diff --git a/serverless/serverless-config-HA.adoc b/serverless/serverless-config-HA.adoc index 18e04877b8..adfdf92b6e 100644 --- a/serverless/serverless-config-HA.adoc +++ b/serverless/serverless-config-HA.adoc @@ -1,6 +1,6 @@ include::modules/serverless-document-attributes.adoc[] [id="serverless-config-HA"] -= Configuring high availability {ServerlessProductName} components += Configuring high-availability {ServerlessProductName} components include::modules/common-attributes.adoc[] :context: serverless-config-HA