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.

Channel workflow overview

If a subscriber rejects an event, there are no re-delivery attempts by default. Developers can configure re-delivery attempts by modifying the delivery spec in a Subscription object.

Creating subscriptions

Developers can create subscriptions that allow event sinks to subscribe to channels and receive events.

Creating subscriptions in the Developer perspective

Prerequisites

To create subscriptions using the Developer perspective, ensure that:

  • The OpenShift Serverless Operator, Knative Serving, and Knative Eventing are installed on your OpenShift Container Platform cluster.

  • You have logged in to the web console.

  • You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.

  • You have created an event sink, such as a Knative service, and a channel.

Procedure
  1. In the Developer perspective, navigate to the Topology page.

  2. Create a subscription using one of the following methods:

    1. Hover over the channel that you want to create a subscription for, and drag the arrow. The Add Subscription option is displayed.

      Create a subscription for the channel
      1. Select your sink as a subscriber from the drop-down list.

      2. Click Add.

    2. If the service is available in the Topology view under the same namespace or project as the channel, click on the channel that you want to create a subscription for, and drag the arrow directly to a service to immediately create a subscription from the channel to that service.

Verification
  • After the subscription has been created, you can see it represented as a line that connects the channel to the service in the Topology view:

    Subscription in the Topology view

    You can view the event source, channel, and subscriptions for the sink by clicking on the service.

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 OpenShift Serverless Operator and Knative Eventing are installed on your OpenShift Container Platform 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 OpenShift Container Platform.

Procedure
  • Create a subscription to connect a sink to a channel:

    $ kn subscription create <subscription_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 OpenShift Serverless Event delivery documentation.
    Example command
    $ kn subscription create mysubscription --channel mychannel --sink ksvc:event-display
    Example output
    Subscription 'mysubscription' created in namespace 'default'.
Verification
  • To confirm that the channel is connected to the event sink, or subscriber, by a subscription, list the existing subscriptions and inspect the output:

    $ kn subscription list
    Example output
    NAME            CHANNEL             SUBSCRIBER           REPLY   DEAD LETTER SINK   READY   REASON
    mysubscription   Channel:mychannel   ksvc:event-display                              True

Creating subscriptions by using YAML

You can create a subscription to connect a channel to a sink by using YAML.

Procedure
  • Create a Subscription object.

    • Create a YAML file and copy the following sample code into it:

      apiVersion: messaging.knative.dev/v1beta1
      kind: Subscription
      metadata:
        name: my-subscription (1)
        namespace: default
      spec:
        channel: (2)
          apiVersion: messaging.knative.dev/v1beta1
          kind: Channel
          name: example-channel
        delivery: (3)
          deadLetterSink:
            ref:
              apiVersion: serving.knative.dev/v1
              kind: Service
              name: error-handler
        subscriber: (4)
          ref:
            apiVersion: serving.knative.dev/v1
            kind: Service
            name: event-display
      1 Name of the subscription.
      2 Configuration settings for the channel that the subscription connects to.
      3 Configuration settings for event delivery. This tells the subscription what happens to events that cannot be delivered to the subscriber. When this is configured, events that failed to be consumed are sent to the deadLetterSink. The event is dropped, no re-delivery of the event is attempted, and an error is logged in the system. The deadLetterSink value must be a Destination.
      4 Configuration settings for the subscriber. This is the event sink that events are delivered to from the channel.
    • Apply the YAML file:

      $ oc apply -f <filename>

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
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 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.

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:

    $ kn subscription describe <subscription_name>
    Example output
    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

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:

    $ kn subscription list
    Example output
    NAME             CHANNEL             SUBSCRIBER           REPLY   DEAD LETTER SINK   READY   REASON
    mysubscription   Channel:mychannel   ksvc:event-display                              True

Updating subscriptions

You can update a subscription by using the kn CLI.

Prerequisites

To update subscriptions using the kn CLI, ensure that:

  • The OpenShift Serverless Operator and Knative Eventing are installed on your OpenShift Container Platform 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 OpenShift Container Platform.

  • You have created a subscription.

Procedure
  • Update a subscription:

    $ 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 OpenShift Serverless Event delivery documentation.
    Example command
    $ kn subscription update mysubscription --sink ksvc:event-display

Deleting subscriptions using the Knative CLI

You can delete a subscription by using the kn CLI.

Procedure
  • Delete a subscription:

    $ kn subscription delete <subscription_name>