diff --git a/modules/serverless-connect-channel-source-odc.adoc b/modules/serverless-connect-channel-source-odc.adoc index c5bd21f724d9..9640b8df3186 100644 --- a/modules/serverless-connect-channel-source-odc.adoc +++ b/modules/serverless-connect-channel-source-odc.adoc @@ -3,7 +3,7 @@ // * serverless/event_workflows/serverless-channels.adoc [id="serverless-connect-channel-source-odc_{context}"] -= Connect an event source to a channel using {product-title} web console += Connect an event source to a channel using the Developer perspective You can create multiple event source types in {product-title} that can be connected to channels. @@ -12,12 +12,12 @@ To connect an event source to a channel using the *Developer* perspective, ensur * The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. * You have logged in to the web console. -* You are in the *Developer* perspective. * 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}. * You have created a channel by following the documentation on _Creating a channel using {product-title} web console_. .Procedure . Create an event source of any type, by following the documentation on _Getting started with event sources_. +. In the *Developer* perspective, navigate to *Event Sources*. . In the *Sink* section of the *Event Sources* form view, select *Resource*. Then use the drop-down to select your channel. + image::sink-pingsource-channel.png[Use your channel as the Resource] diff --git a/modules/serverless-create-channel-kn.adoc b/modules/serverless-create-channel-kn.adoc new file mode 100644 index 000000000000..51ab847b6b28 --- /dev/null +++ b/modules/serverless-create-channel-kn.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-channels.adoc + +[id="serverless-create-channel-kn_{context}"] += Creating a channel using the Knative CLI + +You can create a channel with the cluster default configuration by using the `kn` CLI. + +.Prerequisites + +To create channels using the `kn` CLI, ensure that: + +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. +* You have installed the `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 + +* Create a channel: ++ +[source,terminal] +---- +$ kn channel create --type +---- ++ +The channel type is optional, but where specified, must be given in the format `Group:Version:Kind`. +For example, you can create an `InMemoryChannel` object: ++ +[source,terminal] +---- +$ kn channel create mychannel --type messaging.knative.dev:v1beta1:InMemoryChannel +---- ++ +.Example output +[source,terminal] +---- +Channel 'mychannel' created in namespace 'default'. +---- + +.Verification steps + +* To confirm that the channel now exists, list the existing channels and inspect the output: ++ +[source,terminal] +---- +$ kn channel list +---- ++ +.Example output +[source,terminal] +---- +kn channel list +NAME TYPE URL AGE READY REASON +mychannel InMemoryChannel http://mychannel-kn-channel.default.svc.cluster.local 93s True +---- diff --git a/modules/serverless-create-channel-odc.adoc b/modules/serverless-create-channel-odc.adoc index 2b13e59c4a0c..767a6ec5ec67 100644 --- a/modules/serverless-create-channel-odc.adoc +++ b/modules/serverless-create-channel-odc.adoc @@ -10,9 +10,8 @@ You can create a channel with the cluster default configuration by using the {pr .Prerequisites To create channels using the *Developer* perspective ensure that: -* The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. * You have logged in to the web console. -* You are in the *Developer* perspective. * 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-inmemorychannel-yaml.adoc b/modules/serverless-create-inmemorychannel-yaml.adoc index f4a219755f72..275384dac0e9 100644 --- a/modules/serverless-create-inmemorychannel-yaml.adoc +++ b/modules/serverless-create-inmemorychannel-yaml.adoc @@ -3,22 +3,22 @@ // * serverless/event_workflows/serverless-channels.adoc [id="serverless-create-inmemorychannel-yaml_{context}"] -= Creating a development channel using YAML += Creating a channel using YAML You can create a channel by using YAML with the cluster default configuration. .Prerequisites To create channels ensure that: -* The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. * 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 -. Create a `Channel` object. -.. Create a YAML file and copy the following sample code into it: -+ +To create a `Channel` object: +. Create a YAML file and copy the following sample code into it: ++ [source,yaml] ---- apiVersion: messaging.knative.dev/v1 @@ -27,10 +27,8 @@ metadata: name: example-channel namespace: default ---- - -.. Apply the YAML file: +. Apply the YAML file: + - [source,terminal] ---- $ oc apply -f diff --git a/modules/serverless-create-kn-trigger.adoc b/modules/serverless-create-kn-trigger.adoc index 5ab8b813d6ed..aed725c1a113 100644 --- a/modules/serverless-create-kn-trigger.adoc +++ b/modules/serverless-create-kn-trigger.adoc @@ -7,23 +7,18 @@ The Knative CLI provides a set of `kn trigger` commands that can be used to crea * 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-subscriptions-kn.adoc b/modules/serverless-creating-subscriptions-kn.adoc new file mode 100644 index 000000000000..ef259c0ad5dd --- /dev/null +++ b/modules/serverless-creating-subscriptions-kn.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-channels.adoc + +[id="serverless-creating-subscriptions-kn_{context}"] += Creating subscriptions using the Knative CLI + +You can create a subscription to connect a channel to a sink by using the `kn` CLI. + +.Prerequisites + +To create subscriptions using the `kn` CLI, ensure that: + +* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. +* You have installed the `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 + +* Create a subscription to connect a sink to a channel. ++ +[source,terminal] +---- +$ kn subscription create \ + --channel : \ + --sink : \ + --sink-reply : \ + --sink-dead-letter : +---- ++ +.Example command +[source,terminal] +---- +$ kn subscription create mysubscription --channel mychannel --sink ksvc:event-display +---- ++ +.Example output +[source,terminal] +---- +Subscription 'mysubscription' created in namespace 'default'. +---- + +.Verification steps + +* To confirm that the channel is connected to the event sink, or _subscriber_, by a subscription, list the existing subscriptions and inspect the output: ++ +[source,terminal] +---- +$ kn subscription list +---- ++ +.Example output +[source,terminal] +---- +NAME CHANNEL SUBSCRIBER REPLY DEAD LETTER SINK READY REASON +mysubscription Channel:mychannel ksvc:event-display True +---- diff --git a/modules/serverless-creating-subscriptions-odc.adoc b/modules/serverless-creating-subscriptions-odc.adoc index f1046131bd7d..d1710f064bf0 100644 --- a/modules/serverless-creating-subscriptions-odc.adoc +++ b/modules/serverless-creating-subscriptions-odc.adoc @@ -3,19 +3,18 @@ // * serverless/event_workflows/serverless-channels.adoc [id="serverless-creating-subscriptions-odc_{context}"] -= Connecting a channel to a sink using subscriptions in the Developer perspective += Creating subscriptions in the Developer perspective .Prerequisites To create subscriptions using the *Developer* perspective, ensure that: * The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. * You have logged in to the web console. -* You are in the *Developer* perspective. * 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}. * You have created an event sink, such as a Knative service, and a channel. .Procedure -. Navigate to the *Topology* page. +. In the *Developer* perspective, navigate to the *Topology* page. . Create a subscription using one of the following methods: .. Hover over the channel that you want to create a subscription for, and drag the arrow. The *Add Subscription* option is displayed. + diff --git a/modules/serverless-creating-subscriptions-yaml.adoc b/modules/serverless-creating-subscriptions-yaml.adoc index 6d51f343ca9c..622c85d17a36 100644 --- a/modules/serverless-creating-subscriptions-yaml.adoc +++ b/modules/serverless-creating-subscriptions-yaml.adoc @@ -4,15 +4,15 @@ // * serverless/event_workflows/serverless-channels.adoc [id="serverless-creating-subscriptions-yaml_{context}"] -= Connecting a channel to a sink using subscriptions with YAML += Creating subscriptions by using YAML -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`. +You can create a subscription to connect a channel to a sink by using YAML. .Procedure -. Create a YAML file and copy the following sample code into it: +* Create a `Subscription` object. +** Create a YAML file and copy the following sample code into it: + - [source,yaml] ---- apiVersion: messaging.knative.dev/v1beta1 @@ -37,16 +37,13 @@ spec: 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: +** Apply the YAML file: + - [source,terminal] ---- $ oc apply -f diff --git a/modules/serverless-delete-channel-kn.adoc b/modules/serverless-delete-channel-kn.adoc new file mode 100644 index 000000000000..3afccfcb04c0 --- /dev/null +++ b/modules/serverless-delete-channel-kn.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * serverless/event_workflows/serverless-channels.adoc + +[id="serverless-delete-channel-kn_{context}"] += Deleting a channel using the Knative CLI + +You can delete a channel with the cluster default configuration by using the `kn` CLI. + +.Procedure + +* Delete a channel: ++ +[source,terminal] +---- +$ kn channel delete +---- diff --git a/serverless/event_workflows/serverless-channels.adoc b/serverless/event_workflows/serverless-channels.adoc index 1d43cb2d963a..4f5f55eed9a5 100644 --- a/serverless/event_workflows/serverless-channels.adoc +++ b/serverless/event_workflows/serverless-channels.adoc @@ -6,23 +6,40 @@ include::modules/common-attributes.adoc[] 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. +image::serverless-event-channel-workflow.png[Channel workflow overview] -Developers can create their own channels directly by instantiating a supported `Channel` object. +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. include::modules/serverless-supported-channel-types.adoc[leveloffset=+1] // include::modules/serverless-inmemorychannel.adoc[leveloffset=+2] // comment out for now - this information isn't necessary while only default channel type is available, and should be moved to an admin guide anyway. -include::modules/serverless-create-channel-odc.adoc[leveloffset=+1] + +[id="serverless-channels-creating"] +== Creating channels + +Developers can create channels by instantiating a supported `Channel` object. + +include::modules/serverless-create-channel-odc.adoc[leveloffset=+2] +// include::modules/serverless-create-channel-kn.adoc[leveloffset=+2] +include::modules/serverless-create-inmemorychannel-yaml.adoc[leveloffset=+2] + +[id="serverless-channels-connecting-sources"] +== Connecting a channel to an event source + +Connecting a channel to an event source allows the channel to receive events from that source. +These events can then be forwarded to an event sink by using subscriptions. + include::modules/serverless-connect-channel-source-odc.adoc[leveloffset=+2] -include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+2] -include::modules/serverless-create-inmemorychannel-yaml.adoc[leveloffset=+1] +[id="serverless-channels-creating-subs"] +== Creating subscriptions + +Developers can create subscriptions that allow event sinks to subscribe to channels and receive events directly. + +include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+2] +// include::modules/serverless-creating-subscriptions-kn.adoc[leveloffset=+2] include::modules/serverless-creating-subscriptions-yaml.adoc[leveloffset=+2] + +// include::modules/serverless-delete-channel-kn.adoc[leveloffset=+1] diff --git a/serverless/event_workflows/serverless-create-kn-trigger.adoc b/serverless/event_workflows/serverless-create-kn-trigger.adoc deleted file mode 100644 index 1ee9f7d0f12f..000000000000 --- a/serverless/event_workflows/serverless-create-kn-trigger.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[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/event_workflows/serverless-using-brokers.adoc b/serverless/event_workflows/serverless-using-brokers.adoc index 37a5d86a3096..173b9f415c59 100644 --- a/serverless/event_workflows/serverless-using-brokers.adoc +++ b/serverless/event_workflows/serverless-using-brokers.adoc @@ -11,9 +11,9 @@ After events have entered the broker they can be filtered by event attributes, a image::serverless-event-broker-workflow.png[Broker workflow overview] -You can create the `default` broker by using the `knative-eventing-injection` annotation. +Developers can create the `default` broker by using the `knative-eventing-injection` annotation. -[NOTE] +[IMPORTANT] ==== Although both developers and cluster administrators can add the `knative-eventing-injection` annotation, only cluster administrators can remove brokers created using this annotation. ==== @@ -49,8 +49,19 @@ spec: However, the Knative CLI (`kn`) provides the following commands to simplify creating and managing triggers. +.Prerequisites + +Before you can use triggers, you will need: + +* Knative Eventing and `kn` installed. +* An available broker, either the `default` broker or one that you have created. ++ +You can create the `default` broker either by following the instructions on xref:../serverless-using-brokers.adoc#serverless-using-brokers[Using brokers with Knative Eventing], or by using the `--inject-broker` flag while creating a trigger. Use of this flag is described later in this section. +* An available event consumer, such as a Knative service. + 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-filtering.adoc[leveloffset=+2] include::modules/kn-trigger-update.adoc[leveloffset=+2] include::modules/delete-kn-trigger.adoc[leveloffset=+2] diff --git a/serverless/knative_eventing/serverless-kn-trigger.adoc b/serverless/knative_eventing/serverless-kn-trigger.adoc deleted file mode 100644 index c9bcd5707ca5..000000000000 --- a/serverless/knative_eventing/serverless-kn-trigger.adoc +++ /dev/null @@ -1,80 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-kn-trigger"] -= 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. - -Using triggers allows you to filter events from a channel or 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. - -== Prerequisites -Before you can use triggers, you will need: - -* Knative Eventing and `kn` installed. -* An available broker, either the `default` broker or one that you have created. -+ -You can create the `default` broker either by following the instructions on xref:../serverless-using-brokers.adoc#serverless-using-brokers[Using brokers with Knative Eventing], or by using the `--inject-broker` flag while creating a trigger. Use of this flag is described in the procedure below. -* An available event consumer, for example, a Knative service. - -[id="create-kn-trigger"] -== Creating a trigger using `kn` - -.Procedure - -To create a trigger, enter the following command: - -[source,terminal] ----- -$ kn trigger create --broker --filter --sink ----- - -To create a trigger and also create the `default` broker using broker injection, enter the following command: - -[source,terminal] ----- -$ kn trigger create --inject-broker --filter --sink ----- - -.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. - -include::modules/kn-trigger-list.adoc[leveloffset=+1] -include::modules/kn-trigger-describe.adoc[leveloffset=+1] - -[id="delete-kn-trigger"] -== Deleting a trigger using `kn` - -.Procedure - -To delete a trigger, enter the following command: - -[source,terminal] ----- -$ kn trigger delete ----- - -include::modules/kn-trigger-update.adoc[leveloffset=+1] -include::modules/kn-trigger-filtering.adoc[leveloffset=+1]