diff --git a/_topic_map.yml b/_topic_map.yml index 6c787bdfdb..ce8a297809 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2372,20 +2372,6 @@ Name: Serverless applications Dir: serverless Distros: openshift-enterprise,openshift-webscale Topics: -# Release notes -- Name: Release Notes - File: serverless-release-notes -# Support -- Name: Support - File: serverless-support -# Architecture -- Name: Architecture - Dir: architecture - Topics: - - Name: Knative Serving - File: serverless-serving-architecture - - Name: Knative Eventing - File: serverless-event-architecture # Intro / getting started - Name: Getting started File: serverless-getting-started @@ -2407,6 +2393,14 @@ Topics: File: removing-openshift-serverless - Name: Installing the Knative CLI File: installing-kn +# Architecture +- Name: Architecture + Dir: architecture + Topics: + - Name: Knative Serving + File: serverless-serving-architecture + - Name: Knative Eventing + File: serverless-event-architecture # Apps - Name: Creating and managing serverless applications File: serving-creating-managing-apps @@ -2430,21 +2424,15 @@ Topics: - Name: Splitting traffic between revisions File: splitting-traffic-between-revisions # Knative Eventing -- Name: Knative Eventing - Dir: knative_eventing +- Name: Event workflows + Dir: event_workflows Topics: # Brokers - - Name: Using brokers as an event delivery mechanism + - Name: Event delivery workflows using brokers and triggers File: serverless-using-brokers # Channels - - Name: Using channels + - Name: Event delivery workflows 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 # Sinkbinding - Name: Using SinkBinding File: serverless-sinkbinding @@ -2479,3 +2467,9 @@ Topics: Topics: - Name: Using NVIDIA GPU resources with serverless applications File: gpu-resources +# Release notes +- Name: Release Notes + File: serverless-release-notes +# Support +- Name: Support + File: serverless-support diff --git a/cli_reference/kn-cli-tools.adoc b/cli_reference/kn-cli-tools.adoc index 3636276d7a..394f623260 100644 --- a/cli_reference/kn-cli-tools.adoc +++ b/cli_reference/kn-cli-tools.adoc @@ -28,7 +28,7 @@ Key features of `kn` include: ==== Knative Eventing is currently available as a Technology Preview feature of {ServerlessProductName}. ==== -* Create xref:../serverless/knative_eventing/serverless-sinkbinding.adoc#serverless-sinkbinding[sink binding] to connect existing Kubernetes applications and Knative services. +* Create xref:../serverless/event_workflows/serverless-sinkbinding.adoc#serverless-sinkbinding[sink binding] to connect existing Kubernetes applications and Knative services. * Extend `kn` with flexible plugin architecture, similar to `kubectl`. // * Easily integrate {ServerlessProductName} with OpenShift Pipelines by using `kn` in an OpenShift Pipelines task // TODO: Add integrations later when we have docs about this. diff --git a/images/serverless-event-broker-workflow.png b/images/serverless-event-broker-workflow.png new file mode 100644 index 0000000000..aea669722c Binary files /dev/null and b/images/serverless-event-broker-workflow.png differ diff --git a/images/serverless-event-channel-workflow.png b/images/serverless-event-channel-workflow.png new file mode 100644 index 0000000000..99957bc3ae Binary files /dev/null and b/images/serverless-event-channel-workflow.png differ diff --git a/modules/apiserversource-kn-delete.adoc b/modules/apiserversource-kn-delete.adoc index 32f43fab4d..459a65e2a9 100644 --- a/modules/apiserversource-kn-delete.adoc +++ b/modules/apiserversource-kn-delete.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// serverless/knative_eventing/serverless-kn-source.adoc +// serverless/event_workflows/serverless-kn-source.adoc [id="delete-apiserversource-kn_{context}"] = Deleting the ApiServerSource using the Knative CLI (`kn`) diff --git a/modules/apiserversource-kn.adoc b/modules/apiserversource-kn.adoc index 46f27aba37..e123cde088 100644 --- a/modules/apiserversource-kn.adoc +++ b/modules/apiserversource-kn.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// serverless/knative_eventing/serverless-listing-event-sources.adoc +// serverless/event_workflows/serverless-listing-event-sources.adoc [id="apiserversource-kn_context"] = Using the ApiServerSource with the Knative CLI (`kn`) diff --git a/modules/apiserversource-yaml-delete.adoc b/modules/apiserversource-yaml-delete.adoc index 54ea5c01c8..bb896c9e02 100644 --- a/modules/apiserversource-yaml-delete.adoc +++ b/modules/apiserversource-yaml-delete.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// serverless/knative_eventing/serverless-kn-source.adoc +// serverless/event_workflows/serverless-kn-source.adoc [id="delete-apiserversource-yaml_{context}"] = Deleting the ApiServerSource diff --git a/modules/apiserversource-yaml.adoc b/modules/apiserversource-yaml.adoc index 2920b8c656..e1f70b1103 100644 --- a/modules/apiserversource-yaml.adoc +++ b/modules/apiserversource-yaml.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// serverless/knative_eventing/serverless-listing-event-sources.adoc +// serverless/event_workflows/serverless-listing-event-sources.adoc [id="apiserversource-yaml_context"] = Using the ApiServerSource with the YAML method diff --git a/modules/delete-kn-trigger.adoc b/modules/delete-kn-trigger.adoc new file mode 100644 index 0000000000..dd530ebafa --- /dev/null +++ b/modules/delete-kn-trigger.adoc @@ -0,0 +1,12 @@ +[id="delete-kn-trigger_{context}"] += Deleting a trigger using `kn` + +.Procedure + +* Delete the trigger: ++ + +[source,terminal] +---- +$ kn trigger delete +---- diff --git a/modules/kn-trigger-describe.adoc b/modules/kn-trigger-describe.adoc index 734f35ba97..205ca20d04 100644 --- a/modules/kn-trigger-describe.adoc +++ b/modules/kn-trigger-describe.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-kn-trigger.adoc +// * serverless/event_workflows/serverless-kn-trigger.adoc [id="kn-trigger-describe_{context}"] = Describing a trigger using `kn` @@ -19,8 +19,6 @@ $ kn trigger describe + .Example output -+ - [source,terminal] ---- Name: ping diff --git a/modules/kn-trigger-list.adoc b/modules/kn-trigger-list.adoc index ac74059804..4c1d70bb06 100644 --- a/modules/kn-trigger-list.adoc +++ b/modules/kn-trigger-list.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-kn-trigger.adoc +// * serverless/event_workflows/serverless-kn-trigger.adoc [id="kn-trigger-list_{context}"] = Listing triggers using `kn` @@ -18,8 +18,6 @@ $ kn trigger list + .Example output: -+ - [source,terminal] ---- NAME BROKER SINK AGE CONDITIONS READY REASON @@ -38,3 +36,5 @@ ping default svc:edisplay 32s 5 OK / 5 True ---- $ kn trigger list -o json ---- + +//example output? diff --git a/modules/kn-trigger-update.adoc b/modules/kn-trigger-update.adoc index e5f5e501d5..7951eb712a 100644 --- a/modules/kn-trigger-update.adoc +++ b/modules/kn-trigger-update.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-kn-trigger.adoc +// * serverless/event_workflows/serverless-kn-trigger.adoc [id="kn-trigger-update_{context}"] = Updating a trigger using `kn` @@ -9,21 +9,49 @@ You can use the `kn trigger update` command with certain flags to update attribu .Example +<<<<<<< HEAD . Update a trigger to filter exact event attributes that match incoming events, such as `type=knative.dev.event`: +======= +* To update a trigger, enter the following command: ++ + +[source,terminal] +---- +$ kn trigger update --filter --sink [flags] +---- + ++ +You can update a trigger to filter exact event attributes that match incoming events, such as `type=knative.dev.event`. For example: ++ + +>>>>>>> Updating eventing workflows for GA [source,terminal] ---- $ kn trigger update --filter type=knative.dev.event ---- +<<<<<<< HEAD . Remove the filter attribute with key `type`: +======= ++ +You can also remove a filter attribute from a trigger. +For example, you can remove the filter attribute with key `type`: ++ +>>>>>>> Updating eventing workflows for GA [source,terminal] ---- $ kn trigger update --filter type- ---- +<<<<<<< HEAD . Update the sink of a trigger to use a service named `event-display`: +======= ++ +The following example shows how to update the sink of a trigger to `svc:new-service`: ++ +>>>>>>> Updating eventing workflows for GA [source,terminal] ---- diff --git a/modules/serverless-create-inmemorychannel.adoc b/modules/serverless-create-inmemorychannel.adoc new file mode 100644 index 0000000000..a447f24e12 --- /dev/null +++ b/modules/serverless-create-inmemorychannel.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-channels.adoc + +[id="serverless-create-inmemorychannel_{context}"] += Creating a development channel + +.Procedure + +You can create a channel using the cluster default configuration by completing the following procedure. + +. Create a `Channel` object. +.. Create a YAML file and copy the following sample code into it: ++ + +[source,yaml] +---- +apiVersion: messaging.knative.dev/v1 +kind: Channel +metadata: + name: example-channel + namespace: default +---- + +.. Apply the YAML file by entering: ++ + +[source,terminal] +---- +$ oc apply -f +---- diff --git a/modules/serverless-create-kn-trigger.adoc b/modules/serverless-create-kn-trigger.adoc new file mode 100644 index 0000000000..5ab8b813d6 --- /dev/null +++ b/modules/serverless-create-kn-trigger.adoc @@ -0,0 +1,29 @@ +[id="serverless-create-kn-trigger_{context}"] += Creating a trigger using `kn` + +The Knative CLI provides a set of `kn trigger` commands that can be used to create and manage triggers. + +.Procedure + +* Create a trigger: ++ + +[source,terminal] +---- +$ kn trigger create --broker --filter --sink +---- + ++ +Alternatively, you can create a trigger and simultaneously create the `default` broker using broker injection: ++ + +[source,terminal] +---- +$ kn trigger create --inject-broker --filter --sink +---- + ++ +By default, triggers forward all events sent to a broker to sinks that are subscribed to that broker. ++ +Using the `--filter` attribute for triggers allows you to filter events from a broker, so that subscribers will only receive a subset of events based on your defined criteria. ++ diff --git a/modules/serverless-creating-broker-admin.adoc b/modules/serverless-creating-broker-admin.adoc index 8e90882a88..3767c56961 100644 --- a/modules/serverless-creating-broker-admin.adoc +++ b/modules/serverless-creating-broker-admin.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-using-brokers.adoc +// * serverless/event_workflows/serverless-using-brokers.adoc [id="serverless-creating-broker-admin_{context}"] = Creating a broker as a cluster administrator using namespace annotation diff --git a/modules/serverless-creating-broker.adoc b/modules/serverless-creating-broker.adoc index 1005ab8634..ce6a7be1bf 100644 --- a/modules/serverless-creating-broker.adoc +++ b/modules/serverless-creating-broker.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-using-brokers.adoc +// * serverless/event_workflows/serverless-using-brokers.adoc [id="serverless-creating-broker_{context}"] = Creating a broker as a developer diff --git a/modules/serverless-creating-subscriptions.adoc b/modules/serverless-creating-subscriptions.adoc index e2aa97d943..a22723231d 100644 --- a/modules/serverless-creating-subscriptions.adoc +++ b/modules/serverless-creating-subscriptions.adoc @@ -1,27 +1,16 @@ // Module included in the following assemblies: // // -// * serverless/knative_eventing/serverless-subscriptions.adoc +// * serverless/event_workflows/serverless-channels.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]. +You can create a `Subscription` object to connect a channel to a sink. In the following procedure, the example sink is a Knative service named `error-handler`. .Procedure -. Create a Subscription object to connect a channel to a service, by creating a YAML file containing the following: +. Create a YAML file and copy the following sample code into it: + [source,yaml] @@ -55,7 +44,7 @@ spec: <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: +. Apply the YAML file: + [source,terminal] diff --git a/modules/serverless-deleting-broker-admin.adoc b/modules/serverless-deleting-broker-admin.adoc index d404002df2..c01a3deaed 100644 --- a/modules/serverless-deleting-broker-admin.adoc +++ b/modules/serverless-deleting-broker-admin.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-using-brokers.adoc +// * serverless/event_workflows/serverless-using-brokers.adoc [id="serverless-deleting-broker-admin_{context}"] = Deleting a broker that was created by a cluster administrator using namespace annotation diff --git a/modules/serverless-inmemorychannel.adoc b/modules/serverless-inmemorychannel.adoc index 129dc7db23..2a338d4d3c 100644 --- a/modules/serverless-inmemorychannel.adoc +++ b/modules/serverless-inmemorychannel.adoc @@ -1,51 +1,36 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-channels.adoc +// * serverless/event_workflows/serverless-channels.adoc [id="serverless-inmemorychannel_{context}"] -= Using the default InMemoryChannel configuration += Using the default development channel configuration -InMemoryChannels are for development use only, and should not be used in a production environment. - -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. 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: +When you install Knative Eventing, the following `default-ch-webhook` config map is created automatically in the `knative-eventing` namespace: [source,yaml] ---- apiVersion: v1 kind: ConfigMap metadata: + name: default-ch-webhook namespace: knative-eventing - name: config-br-default-channel data: - channelTemplateSpec: | - apiVersion: messaging.knative.dev/v1 - kind: InMemoryChannel + default-ch-config: | + clusterDefault: + apiVersion: messaging.knative.dev/v1 + kind: InMemoryChannel + namespaceDefaults: + some-namespace: + apiVersion: messaging.knative.dev/v1 + kind: InMemoryChannel ---- -.Creating a channel using the cluster default configuration +This config map can specify either a cluster-wide default channel implementation, or a namespace-specific default channel implementation. +Configuring a namespace-specific default overrides any cluster-wide settings. -* Create a generic Channel custom object. -+ - -[source,yaml] ----- -apiVersion: messaging.knative.dev/v1 -kind: Channel -metadata: - name: example-channel - namespace: default ----- - -+ -When the 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. -+ +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. +.Example `Channel` object with `spec.channelTemplate` properties [source,yaml] ---- apiVersion: messaging.knative.dev/v1 @@ -59,10 +44,15 @@ spec: kind: InMemoryChannel ---- -The channel controller then creates 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. +The channel controller then creates the backing channel instance based on the `spec.channelTemplate` configuration. -When this mechanism is used, two objects are created: a generic channel, and an InMemoryChannel type channel. +[NOTE] +==== +The `spec.channelTemplate` properties cannot be changed after creation, because they are set by the default channel mechanism rather than by the user. +==== -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 type channel. +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` channel, 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-pingsource-kn.adoc b/modules/serverless-pingsource-kn.adoc index 931f70b8e4..d674580a92 100644 --- a/modules/serverless-pingsource-kn.adoc +++ b/modules/serverless-pingsource-kn.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-pingsource.adoc +// * serverless/event_workflows/serverless-pingsource.adoc [id="serverless-pingsource-kn_{context}"] = Using a PingSource with the `kn` CLI diff --git a/modules/serverless-pingsource-yaml.adoc b/modules/serverless-pingsource-yaml.adoc index fd890e6945..4e7e57c8d0 100644 --- a/modules/serverless-pingsource-yaml.adoc +++ b/modules/serverless-pingsource-yaml.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// * serverless/knative_eventing/serverless-pingsource.adoc +// * serverless/event_workflows/serverless-pingsource.adoc [id="serverless-pingsource-yaml_{context}"] = Using a PingSource with YAML diff --git a/modules/serverless-service-ac-event-sources.adoc b/modules/serverless-service-ac-event-sources.adoc index 1cbcadd2f3..ddad894d64 100644 --- a/modules/serverless-service-ac-event-sources.adoc +++ b/modules/serverless-service-ac-event-sources.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// serverless/knative_eventing/serverless-listing-event-sources.adoc +// serverless/event_workflows/serverless-listing-event-sources.adoc [id="serverless-service-ac-event-sources_context"] = Creating a service account, role, and binding for event sources diff --git a/modules/serverless-sinkbinding-kn.adoc b/modules/serverless-sinkbinding-kn.adoc index 4079e69859..e98c9f14cb 100644 --- a/modules/serverless-sinkbinding-kn.adoc +++ b/modules/serverless-sinkbinding-kn.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// serverless/knative_eventing/serverless-sinkbinding.adoc +// serverless/event_workflows/serverless-sinkbinding.adoc [id="serverless-sinkbinding-kn_{context}"] = Using SinkBinding with the Knative CLI (`kn`) diff --git a/modules/serverless-sinkbinding-yaml.adoc b/modules/serverless-sinkbinding-yaml.adoc index 0547aed2e5..73f6fe9bc5 100644 --- a/modules/serverless-sinkbinding-yaml.adoc +++ b/modules/serverless-sinkbinding-yaml.adoc @@ -1,6 +1,6 @@ // Module included in the following assemblies: // -// serverless/knative_eventing/serverless-sinkbinding.adoc +// serverless/event_workflows/serverless-sinkbinding.adoc [id="serverless-sinkbinding-yaml_{context}"] = Using SinkBinding with the YAML method diff --git a/serverless/architecture/serverless-event-architecture.adoc b/serverless/architecture/serverless-event-architecture.adoc index af489df6d0..b42cb00d2a 100644 --- a/serverless/architecture/serverless-event-architecture.adoc +++ b/serverless/architecture/serverless-event-architecture.adoc @@ -14,9 +14,8 @@ These events conform to the link:https://cloudevents.io[CloudEvents specificatio You can propagate an event from an xref:../event_sources/knative-event-sources.adoc#knative-event-sources[event source] to multiple event sinks by using: -* xref:../knative_eventing/serverless-channels.adoc#serverless-channels[channels] and subscriptions, or -* xref:../knative_eventing/serverless-using-brokers.adoc#serverless-using-brokers[brokers] and xref:../knative_eventing/serverless-kn-trigger.adoc#serverless-kn-trigger[triggers]. -// TODO: Add subscription docs +* xref:../event_workflows/serverless-channels.adoc#serverless-channels[channels] and subscriptions, or +* xref:../event_workflows/serverless-using-brokers.adoc#serverless-using-brokers[brokers] and triggers. Events are buffered if the destination sink is unavailable. // For more information about creating an Event delivery system, see diff --git a/serverless/event_sources/knative-event-sources.adoc b/serverless/event_sources/knative-event-sources.adoc index cf1611dca1..a9eb9117ab 100644 --- a/serverless/event_sources/knative-event-sources.adoc +++ b/serverless/event_sources/knative-event-sources.adoc @@ -12,7 +12,7 @@ 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. -xref:../../serverless/knative_eventing/serverless-sinkbinding.adoc#serverless-sinkbinding[SinkBinding] is also supported, which allows you to connect core Kubernetes resources such as Deployment, Job, or StatefulSet with a sink. +xref:../../serverless/event_workflows/serverless-sinkbinding.adoc#serverless-sinkbinding[SinkBinding] is also supported, which allows you to connect core Kubernetes resources such as Deployment, Job, or StatefulSet with a sink. You can create and manage Knative event sources using the **Developer** perspective in the {product-title} web console, the `kn` CLI, or by applying YAML files. diff --git a/serverless/knative_eventing/images b/serverless/event_workflows/images similarity index 100% rename from serverless/knative_eventing/images rename to serverless/event_workflows/images diff --git a/serverless/knative_eventing/modules b/serverless/event_workflows/modules similarity index 100% rename from serverless/knative_eventing/modules rename to serverless/event_workflows/modules diff --git a/serverless/event_workflows/serverless-channels.adoc b/serverless/event_workflows/serverless-channels.adoc new file mode 100644 index 0000000000..841ee768de --- /dev/null +++ b/serverless/event_workflows/serverless-channels.adoc @@ -0,0 +1,34 @@ +include::modules/serverless-document-attributes.adoc[] +[id="serverless-channels"] += Event delivery workflows using channels +include::modules/common-attributes.adoc[] +:context: serverless-channels + +toc::[] + +Events can be sent from a source to a sink by using channels and subscriptions for event delivery. + +image::serverless-event-channel-workflow.png[Channel workflow overview] +// just sources or do we need to talk about other event producers? + +Channels are custom resources 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, or other sinks, by using a subscription. + +The default configuration for channel instances is defined in the `default-ch-webhook` ConfigMap. +Developers can create their own channels directly by instantiating a supported `Channel` object. + +[id="serverless-channels-supported-types"] +== Supported channel types + +Currently, {ServerlessProductName} only supports `InMemoryChannel` kind channels for development use, as part of the Knative Eventing Technology Preview. + +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. + +include::modules/serverless-inmemorychannel.adoc[leveloffset=+2] +include::modules/serverless-create-inmemorychannel.adoc[leveloffset=+1] +include::modules/serverless-creating-subscriptions.adoc[leveloffset=+1] diff --git a/serverless/event_workflows/serverless-create-kn-trigger.adoc b/serverless/event_workflows/serverless-create-kn-trigger.adoc new file mode 100644 index 0000000000..1ee9f7d0f1 --- /dev/null +++ b/serverless/event_workflows/serverless-create-kn-trigger.adoc @@ -0,0 +1,27 @@ +[id="serverless-create-kn-trigger_{context}"] += Creating a trigger using `kn` + +All events that are sent to a broker will be sent to all of the subscribers of that broker by default. + +Using triggers allows you to filter events from a broker, so that subscribers will only receive a subset of events based on your defined criteria. + +The Knative CLI provides a set of `kn trigger` commands that can be used to create and manage triggers. + +.Procedure + +* Create a trigger: ++ + +[source,terminal] +---- +$ kn trigger create --broker --filter --sink +---- + ++ +Alternatively, you can create a trigger and simultaneously create the `default` broker using broker injection: ++ + +[source,terminal] +---- +$ kn trigger create --inject-broker --filter --sink +---- diff --git a/serverless/knative_eventing/serverless-sinkbinding.adoc b/serverless/event_workflows/serverless-sinkbinding.adoc similarity index 100% rename from serverless/knative_eventing/serverless-sinkbinding.adoc rename to serverless/event_workflows/serverless-sinkbinding.adoc diff --git a/serverless/event_workflows/serverless-using-brokers.adoc b/serverless/event_workflows/serverless-using-brokers.adoc new file mode 100644 index 0000000000..37a5d86a30 --- /dev/null +++ b/serverless/event_workflows/serverless-using-brokers.adoc @@ -0,0 +1,56 @@ +[id="serverless-using-brokers"] += Event delivery workflows using brokers and triggers +include::modules/common-attributes.adoc[] +include::modules/serverless-document-attributes.adoc[] +:context: serverless-using-brokers + +toc::[] + +Events are sent from an event source to your broker as an HTTP POST request. +After events have entered the broker they can be filtered by event attributes, and sent as an HTTP POST request to an event sink by using triggers. + +image::serverless-event-broker-workflow.png[Broker workflow overview] + +You can create the `default` broker by using the `knative-eventing-injection` annotation. + +[NOTE] +==== +Although both developers and cluster administrators can add the `knative-eventing-injection` annotation, only cluster administrators can remove brokers created using this annotation. +==== + +include::modules/serverless-creating-broker.adoc[leveloffset=+1] +include::modules/serverless-creating-broker-admin.adoc[leveloffset=+1] +include::modules/serverless-deleting-broker-admin.adoc[leveloffset=+2] + +[id="serverless-using-brokers-triggers"] +== Using triggers + +You can create triggers using YAML, as shown in the following example: + +.Example trigger YAML +[source,yaml] +---- +apiVersion: eventing.knative.dev/v1alpha1 +kind: Trigger +metadata: + name: trigger-example <1> +spec: + broker: default <2> + subscriber: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: my-service <3> +---- + +<1> The name of the trigger. +<2> The name of the broker where events will be filtered from. If the broker is not specified, the trigger will revert to using the `default` broker. +<3> The name of the service that will consumer filtered events. + +However, the Knative CLI (`kn`) provides the following commands to simplify creating and managing triggers. + +include::modules/serverless-create-kn-trigger.adoc[leveloffset=+2] +include::modules/kn-trigger-list.adoc[leveloffset=+2] +include::modules/kn-trigger-describe.adoc[leveloffset=+2] +include::modules/kn-trigger-update.adoc[leveloffset=+2] +include::modules/delete-kn-trigger.adoc[leveloffset=+2] diff --git a/serverless/installing_serverless/installing-knative-eventing.adoc b/serverless/installing_serverless/installing-knative-eventing.adoc index 1d30f1f62f..fdd146e570 100644 --- a/serverless/installing_serverless/installing-knative-eventing.adoc +++ b/serverless/installing_serverless/installing-knative-eventing.adoc @@ -18,6 +18,7 @@ This guide provides information about installing Knative Eventing using the defa include::modules/serverless-create-eventing-namespace.adoc[leveloffset=+1] +[id="installing-knative-eventing-prerequisites"] == Prerequisites * An {product-title} account with cluster administrator access * Installed {ServerlessOperatorName} @@ -26,7 +27,7 @@ include::modules/serverless-create-eventing-namespace.adoc[leveloffset=+1] include::modules/serverless-install-eventing-web-console.adoc[leveloffset=+1] include::modules/serverless-install-eventing-yaml.adoc[leveloffset=+1] +[id="installing-knative-eventing-next-steps"] == Next steps -* For services and serving functionality on {ServerlessProductName}, you can install the Knative Serving component. See the documentation on xref:../installing_serverless/installing-knative-serving.adoc#installing-knative-serving[Installing Knative Serving]. * Install the Knative CLI to use `kn` commands with Knative Eventing. For example, `kn source` commands. See the documentation on xref:../installing_serverless/installing-kn#installing-kn[Installing the Knative CLI (`kn`)]. diff --git a/serverless/knative_eventing/serverless-channels.adoc b/serverless/knative_eventing/serverless-channels.adoc deleted file mode 100644 index 32dd754bdd..0000000000 --- a/serverless/knative_eventing/serverless-channels.adoc +++ /dev/null @@ -1,19 +0,0 @@ -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 type channels as part of the Knative Eventing Technology Preview. - -include::modules/serverless-inmemorychannel.adoc[leveloffset=+1] diff --git a/serverless/knative_eventing/serverless-subscriptions.adoc b/serverless/knative_eventing/serverless-subscriptions.adoc deleted file mode 100644 index e4a1133d0a..0000000000 --- a/serverless/knative_eventing/serverless-subscriptions.adoc +++ /dev/null @@ -1,11 +0,0 @@ -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] diff --git a/serverless/knative_eventing/serverless-using-brokers.adoc b/serverless/knative_eventing/serverless-using-brokers.adoc deleted file mode 100644 index fb7b947462..0000000000 --- a/serverless/knative_eventing/serverless-using-brokers.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="serverless-using-brokers"] -= Using brokers as an event delivery mechanism -include::modules/common-attributes.adoc[] -include::modules/serverless-document-attributes.adoc[] -:context: serverless-using-brokers - -toc::[] - -You can use an xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[event source] or a xref:../../serverless/knative_eventing/serverless-sinkbinding.adoc#serverless-sinkbinding[SinkBinding], the `default` broker, and a trigger together to decouple applications that produce events from the destination configuration. - -Events are sent from an event source to the broker as an HTTP POST request. -After events have entered the broker, they can be filtered and sent to an event sink by using triggers. -You can use a trigger to consume events from a broker based on event attributes. Your application will receive events as an HTTP POST request. - -You can create the `default` broker by using the `knative-eventing-injection` annotation. - -[NOTE] -==== -Although both developers and cluster administrators can add the `knative-eventing-injection` annotation, only cluster administrators can remove brokers created using this annotation. -==== - -include::modules/serverless-creating-broker.adoc[leveloffset=+1] -include::modules/serverless-creating-broker-admin.adoc[leveloffset=+1] -include::modules/serverless-deleting-broker-admin.adoc[leveloffset=+1] diff --git a/serverless/serverless-getting-started.adoc b/serverless/serverless-getting-started.adoc index 4b12ccd035..7d4ff55783 100644 --- a/serverless/serverless-getting-started.adoc +++ b/serverless/serverless-getting-started.adoc @@ -30,4 +30,3 @@ include::modules/technology-preview.adoc[leveloffset=+2] * Install the xref:../serverless/installing_serverless/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessOperatorName}] on your {product-title} cluster to get started. * View the xref:../serverless/serverless-release-notes.adoc#serverless-release-notes[{ServerlessProductName} release notes]. -* Create an application by following the documentation on xref:../serverless/serving-creating-managing-apps.adoc#serving-creating-managing-apps[Creating and managing serverless applications].