mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 21:46:22 +01:00
Adding event delivery parameter docs
This commit is contained in:
Ashleigh Brennan
committed by
openshift-cherrypick-robot
openshift-cherrypick-robot
parent
96cc4ecd1d
commit
08224ba92a
@@ -2828,15 +2828,21 @@ Topics:
|
||||
- Name: Splitting traffic between revisions
|
||||
File: splitting-traffic-between-revisions-knative
|
||||
# Knative Eventing
|
||||
- Name: Event workflows
|
||||
- Name: Knative Eventing workflows
|
||||
Dir: event_workflows
|
||||
Topics:
|
||||
# Brokers
|
||||
- Name: Event delivery workflows using brokers and triggers
|
||||
- Name: Broker and trigger workflows
|
||||
File: serverless-using-brokers
|
||||
# Channels
|
||||
- Name: Event delivery workflows using channels
|
||||
- Name: Channel workflows
|
||||
File: serverless-channels
|
||||
# Subscriptions
|
||||
- Name: Using subscriptions
|
||||
File: serverless-subs
|
||||
# Event delivery
|
||||
- Name: Event delivery
|
||||
File: serverless-event-delivery
|
||||
# Event sources
|
||||
- Name: Event sources
|
||||
Dir: event_sources
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * serverless/event_workflows/serverless-channels.adoc
|
||||
// * serverless/event_workflows/serverless-subs.adoc
|
||||
|
||||
[id="serverless-creating-subscriptions-kn_{context}"]
|
||||
= Creating subscriptions using the Knative CLI
|
||||
@@ -17,16 +17,21 @@ To create subscriptions using the `kn` CLI, ensure that:
|
||||
|
||||
.Procedure
|
||||
|
||||
* Create a subscription to connect a sink to a channel.
|
||||
* Create a subscription to connect a sink to a channel:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ kn subscription create <subscription_name> \
|
||||
--channel <Group:Version:Kind>:<channel_name> \
|
||||
--sink <sink_prefix>:<sink_name> \
|
||||
--sink-reply <sink_prefix>:<sink_name> \
|
||||
--sink-dead-letter <sink_prefix>:<sink_name>
|
||||
--channel <group:version:kind>:<channel_name> \ <1>
|
||||
--sink <sink_prefix>:<sink_name> \ <2>
|
||||
--sink-dead-letter <sink_prefix>:<sink_name> <3>
|
||||
----
|
||||
<1> `--channel` specifies the source for cloud events that should be processed. You must provide the channel name. If you are not using the default `InMemoryChannel` channel that is backed by the `Channel` resource, you must prefix the channel name with the `<group:version:kind>` for the specified channel type. For example, this will be `messaging.knative.dev:v1beta1:KafkaChannel` for a Kafka backed channel.
|
||||
<2> `--sink` specifies the target destination to which the event should be delivered. By default, the `<sink_name>` is interpreted as a Knative service of this name, in the same namespace as the subscription. You can specify the type of the sink by using one of the following prefixes:
|
||||
`ksvc`:: A Knative service.
|
||||
`channel`:: A channel that should be used as destination. Only default channel types can be referenced here.
|
||||
`broker`:: An Eventing broker.
|
||||
<3> Optional: `--sink-dead-letter` is an optional flag that can be used to specify a sink which events should be sent to in cases where events fail to be delivered. For more information, see the {ServerlessProductName} _Event delivery_ documentation.
|
||||
+
|
||||
.Example command
|
||||
[source,terminal]
|
||||
|
||||
17
modules/serverless-deleting-subscriptions-kn.adoc
Normal file
17
modules/serverless-deleting-subscriptions-kn.adoc
Normal file
@@ -0,0 +1,17 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * serverless/event_workflows/serverless-subs.adoc
|
||||
|
||||
[id="serverless-deleting-subscriptions-kn_{context}"]
|
||||
= Deleting subscriptions using the Knative CLI
|
||||
|
||||
You can delete a subscription by using the `kn` CLI.
|
||||
|
||||
.Procedure
|
||||
|
||||
* Delete a subscription:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ kn subscription delete <subscription_name>
|
||||
----
|
||||
49
modules/serverless-describe-subs-kn.adoc
Normal file
49
modules/serverless-describe-subs-kn.adoc
Normal file
@@ -0,0 +1,49 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * serverless/event_workflows/serverless-subs.adoc
|
||||
|
||||
[id="serverless-describe-subs-kn_{context}"]
|
||||
= Describing subscriptions using the Knative CLI
|
||||
|
||||
You can print information about a subscription in the terminal by using the `kn` CLI.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
To describe subscriptions using the `kn` CLI, ensure that:
|
||||
|
||||
* You have installed the `kn` CLI.
|
||||
* You have created a subscription in your cluster.
|
||||
|
||||
.Procedure
|
||||
|
||||
* Describe a subscription:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ kn subscription describe <subscription_name>
|
||||
----
|
||||
+
|
||||
.Example output
|
||||
[source,terminal]
|
||||
----
|
||||
Name: my-subscription
|
||||
Namespace: default
|
||||
Annotations: messaging.knative.dev/creator=openshift-user, messaging.knative.dev/lastModifier=min ...
|
||||
Age: 43s
|
||||
Channel: Channel:my-channel (messaging.knative.dev/v1)
|
||||
Subscriber:
|
||||
URI: http://edisplay.default.example.com
|
||||
Reply:
|
||||
Name: default
|
||||
Resource: Broker (eventing.knative.dev/v1)
|
||||
DeadLetterSink:
|
||||
Name: my-sink
|
||||
Resource: Service (serving.knative.dev/v1)
|
||||
|
||||
Conditions:
|
||||
OK TYPE AGE REASON
|
||||
++ Ready 43s
|
||||
++ AddedToChannel 43s
|
||||
++ ChannelReady 43s
|
||||
++ ReferencesResolved 43s
|
||||
----
|
||||
20
modules/serverless-event-delivery-component-behaviors.adoc
Normal file
20
modules/serverless-event-delivery-component-behaviors.adoc
Normal file
@@ -0,0 +1,20 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// serverless/event_workflows/serverless-event-delivery.adoc
|
||||
|
||||
[id="serverless-event-delivery-component-behaviors_{context}"]
|
||||
= Event delivery behavior for Knative Eventing channels
|
||||
|
||||
Different Knative Eventing channel types have their own behavior patterns that are followed for event delivery. Developers can set event delivery parameters in the subscription configuration to ensure that any events that fail to be delivered from channels to an event sink are retried. You must also configure a dead letter sink for subscriptions if you want to provide a sink where events that are not eventually delivered can be stored, otherwise undelivered events are dropped.
|
||||
|
||||
== Event delivery behavior for Apache Kafka channels
|
||||
|
||||
If an event is successfully delivered to a Kafka channel or broker receiver, the receiver responds with a `202` status code, which means that the event has been safely stored inside a Kafka topic and is not lost. If the receiver responds with any other status code, the event is not safely stored, and steps must be taken by the user to resolve this issue.
|
||||
|
||||
== Delivery failure status codes
|
||||
|
||||
The channel or broker receiver can respond with the following status codes if an event fails to be delivered:
|
||||
|
||||
`500`:: This is a generic status code which means that the event was not delivered successfully.
|
||||
`404`:: This status code means that the channel or broker the event is being delivered to does not exist, or that the `Host` header is incorrect.
|
||||
`400`:: This status code means that the event being sent to the receiver is invalid.
|
||||
35
modules/serverless-list-subs-kn.adoc
Normal file
35
modules/serverless-list-subs-kn.adoc
Normal file
@@ -0,0 +1,35 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * serverless/event_workflows/serverless-subs.adoc
|
||||
|
||||
[id="serverless-list-subs-kn_{context}"]
|
||||
= Listing subscriptions using the Knative CLI
|
||||
|
||||
You can list existing subscriptions on your cluster by using the `kn` CLI.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
* You have installed the `kn` CLI.
|
||||
|
||||
.Procedure
|
||||
|
||||
* List subscriptions on your cluster:
|
||||
+
|
||||
[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
|
||||
----
|
||||
// . Optional: List subscriptions in YAML format:
|
||||
// +
|
||||
// [source,terminal]
|
||||
// ----
|
||||
// $ kn subscription list -o yaml
|
||||
// ----
|
||||
// Add this step once I have an example output, optional so non urgent
|
||||
34
modules/serverless-subscription-event-delivery-config.adoc
Normal file
34
modules/serverless-subscription-event-delivery-config.adoc
Normal file
@@ -0,0 +1,34 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// serverless/event_workflows/serverless-event-delivery.adoc
|
||||
|
||||
[id="serverless-subscription-event-delivery-config_{context}"]
|
||||
= Configuring event delivery failure parameters using subscriptions
|
||||
|
||||
Developers can configure event delivery parameters for individual subscriptions by modifying the `delivery` settings for a `Subscription` object.
|
||||
|
||||
.Example subscription YAML
|
||||
[source,yaml]
|
||||
----
|
||||
apiVersion: messaging.knative.dev/v1
|
||||
kind: Subscription
|
||||
metadata:
|
||||
name: <subscription_name>
|
||||
namespace: <subscription_namespace>
|
||||
spec:
|
||||
delivery:
|
||||
deadLetterSink: <1>
|
||||
ref:
|
||||
apiVersion: serving.knative.dev/v1
|
||||
kind: Service
|
||||
name: <sink_name>
|
||||
backoffDelay: <duration> <2>
|
||||
backoffPolicy: <policy_type> <3>
|
||||
retry: <integer> <4>
|
||||
----
|
||||
<1> Configuration settings to enable using a dead letter sink. This tells the subscription what happens to events that cannot be delivered to the subscriber.
|
||||
+
|
||||
When this is configured, events that fail to be delivered are sent to the dead letter sink destination. The destination can be a Knative service or a URI.
|
||||
<2> You can set the `backoffDelay` delivery parameter to specify the time delay before an event delivery retry is attempted after a failure. The duration of the `backoffDelay` parameter is specified using the https://en.wikipedia.org/wiki/ISO_8601#Durations[ISO 8601] format. For example, `PT1S` specifies a 1 second delay.
|
||||
<3> The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either `linear` or `exponential`. When using the `linear` back off policy, the back off delay is the time interval specified between retries. When using the `exponential` back off policy, the back off delay is equal to `backoffDelay*2^<numberOfRetries>`.
|
||||
<4> The number of times that event delivery is retried before the event is sent to the dead letter sink.
|
||||
39
modules/serverless-update-subscriptions-kn.adoc
Normal file
39
modules/serverless-update-subscriptions-kn.adoc
Normal file
@@ -0,0 +1,39 @@
|
||||
// Module included in the following assemblies:
|
||||
//
|
||||
// * serverless/event_workflows/serverless-subs.adoc
|
||||
|
||||
[id="serverless-update-subscriptions-kn_{context}"]
|
||||
= Updating subscriptions
|
||||
|
||||
You can update a subscription by using the `kn` CLI.
|
||||
|
||||
.Prerequisites
|
||||
|
||||
To update 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 access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
|
||||
* You have created a subscription.
|
||||
|
||||
.Procedure
|
||||
|
||||
* Update a subscription:
|
||||
+
|
||||
[source,terminal]
|
||||
----
|
||||
$ kn subscription update <subscription_name> \
|
||||
--sink <sink_prefix>:<sink_name> \ <1>
|
||||
--sink-dead-letter <sink_prefix>:<sink_name> <2>
|
||||
----
|
||||
<1> `--sink` specifies the updated target destination to which the event should be delivered. You can specify the type of the sink by using one of the following prefixes:
|
||||
`ksvc`:: A Knative service.
|
||||
`channel`:: A channel that should be used as destination. Only default channel types can be referenced here.
|
||||
`broker`:: An Eventing broker.
|
||||
<2> Optional: `--sink-dead-letter` is an optional flag that can be used to specify a sink which events should be sent to in cases where events fail to be delivered. For more information, see the {ServerlessProductName} _Event delivery_ documentation.
|
||||
+
|
||||
.Example command
|
||||
[source,terminal]
|
||||
----
|
||||
$ kn subscription update mysubscription --sink ksvc:event-display
|
||||
----
|
||||
@@ -1,6 +1,6 @@
|
||||
include::modules/serverless-document-attributes.adoc[]
|
||||
[id="serverless-channels"]
|
||||
= Event delivery workflows using channels
|
||||
= Channel workflows
|
||||
include::modules/common-attributes.adoc[]
|
||||
:context: serverless-channels
|
||||
|
||||
@@ -39,14 +39,10 @@ These events can then be forwarded to an event sink by using subscriptions.
|
||||
|
||||
include::modules/serverless-connect-channel-source-odc.adoc[leveloffset=+2]
|
||||
|
||||
[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]
|
||||
|
||||
// delete channels
|
||||
// deleting channels
|
||||
include::modules/serverless-delete-channel-kn.adoc[leveloffset=+1]
|
||||
|
||||
[id="serverless-channels-next-steps"]
|
||||
== Next steps
|
||||
|
||||
* After you have created a channel, see xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs[Using subscriptions] for information about creating and using subscriptions for event delivery.
|
||||
|
||||
33
serverless/event_workflows/serverless-event-delivery.adoc
Normal file
33
serverless/event_workflows/serverless-event-delivery.adoc
Normal file
@@ -0,0 +1,33 @@
|
||||
include::modules/serverless-document-attributes.adoc[]
|
||||
[id="serverless-event-delivery"]
|
||||
= Event delivery
|
||||
include::modules/common-attributes.adoc[]
|
||||
:context: serverless-event-delivery
|
||||
|
||||
toc::[]
|
||||
|
||||
You can configure event delivery parameters for Knative Eventing that are applied in cases where an event fails to be delivered by a xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs[subscription]. Event delivery parameters are configured individually per subscription.
|
||||
// TODO: Update docs to add triggers once this is implemented.
|
||||
|
||||
include::modules/serverless-event-delivery-component-behaviors.adoc[leveloffset=+1]
|
||||
|
||||
[id="serverless-event-delivery-parameters"]
|
||||
== Configurable parameters
|
||||
|
||||
The following parameters can be configured for event delivery.
|
||||
|
||||
Dead letter sink:: You can configure the `deadLetterSink` delivery parameter so that if an event fails to be delivered it is sent to the specified event sink.
|
||||
|
||||
Retries:: You can set a minimum number of times that the delivery must be retried before the event is sent to the dead letter sink, by configuring the `retry` delivery parameter with an integer value.
|
||||
|
||||
Back off delay:: You can set the `backoffDelay` delivery parameter to specify the time delay before an event delivery retry is attempted after a failure. The duration of the `backoffDelay` parameter is specified using the https://en.wikipedia.org/wiki/ISO_8601#Durations[ISO 8601] format.
|
||||
|
||||
Back off policy:: The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either `linear` or `exponential`. When using the `linear` back off policy, the back off delay is the time interval specified between retries. When using the `exponential` backoff policy, the back off delay is equal to `backoffDelay*2^<numberOfRetries>`.
|
||||
|
||||
include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1]
|
||||
|
||||
[id="serverless-event-delivery-additional-resources"]
|
||||
== Additional resources
|
||||
|
||||
* See xref:../../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Knative Eventing workflows using channels] for more information about subscriptions.
|
||||
* See xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs-creating-subs[Creating subscriptions].
|
||||
32
serverless/event_workflows/serverless-subs.adoc
Normal file
32
serverless/event_workflows/serverless-subs.adoc
Normal file
@@ -0,0 +1,32 @@
|
||||
include::modules/serverless-document-attributes.adoc[]
|
||||
[id="serverless-subs"]
|
||||
= Using subscriptions
|
||||
include::modules/common-attributes.adoc[]
|
||||
:context: serverless-subs
|
||||
|
||||
toc::[]
|
||||
|
||||
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]
|
||||
|
||||
If a subscriber rejects an event, there are no re-delivery attempts by default. Developers can configure xref:../../serverless/event_workflows/serverless-event-delivery.adoc#serverless-event-delivery[re-delivery attempts] by modifying the `delivery` spec in a `Subscription` object.
|
||||
|
||||
[id="serverless-subs-creating-subs"]
|
||||
== Creating subscriptions
|
||||
|
||||
Developers can create subscriptions that allow event sinks to subscribe to channels and receive events.
|
||||
|
||||
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]
|
||||
// config event delivery
|
||||
include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1]
|
||||
// describe subs
|
||||
include::modules/serverless-describe-subs-kn.adoc[leveloffset=+1]
|
||||
// list subs
|
||||
include::modules/serverless-list-subs-kn.adoc[leveloffset=+1]
|
||||
// update subs
|
||||
include::modules/serverless-update-subscriptions-kn.adoc[leveloffset=+1]
|
||||
// delete subs
|
||||
include::modules/serverless-deleting-subscriptions-kn.adoc[leveloffset=+1]
|
||||
@@ -1,5 +1,5 @@
|
||||
[id="serverless-using-brokers"]
|
||||
= Event delivery workflows using brokers and triggers
|
||||
= Broker and trigger workflows
|
||||
include::modules/common-attributes.adoc[]
|
||||
include::modules/serverless-document-attributes.adoc[]
|
||||
:context: serverless-using-brokers
|
||||
|
||||
Reference in New Issue
Block a user