Kyma Event Bus allows you to integrate various external solutions with Kyma. To achieve successful integration, the Event Bus uses the publish-subscribe messaging pattern that allows Kyma to receive business Events from different solutions, enrich them, and trigger business flows using lambdas or services defined in Kyma.

The Event Bus is based on the NATS Streaming open-source log-based streaming system for cloud-native applications, which is a brokered messaging middleware and Knative Eventing. The Event Bus provides an at-least-once delivery guarantee meaning the messages are retransmitted to assure they are successfully delivered at least once.

NOTE: Explore and test the new functionality provided by Knative Eventing Mesh. For details, read this document.

Event consumption

When you create a lambda or a service to perform a given business functionality, you must define which Events trigger it. Define triggers by creating the Subscription CR where you instruct the Event Bus to forward the Events of a particular type to your lambda. For example, whenever the order-created Event comes in, the Event Bus stores it in NATS Streaming. It then dispatches it to the receiver specified in the Subscription CR definition.

NOTE: The Event Bus creates a separate Event trigger for each Subscription.

1. A user creates a lambda or a service that an Event coming from an external solution triggers.

   NOTE: When creating a service, the user must create a Kyma Subscription resource manually. If the user uses Kyma Console UI to create a lambda, the Subscription resource is created automatically.

2. Event Bus Subscription Controller reacts to the creation of Kyma Subscription. It verifies if the Event type from the application can be consumed in the Namespace where the Kyma Subscription has been created. If so, it creates the Knative Channel and Knative Subscription resources.

3. Knative Eventing Controller reacts to the creation of Knative Channel and creates a NatssChannel resource with all the necessary specification about the subscriber.
4. NatssChannel Controller reacts to the creation of a NatssChannel and creates the required Kubernetes services. NatssChannel Dispatcher also reacts to the creation of a NatssChannel and creates the NATSS Streaming Subscription.
5. NatssChannel Dispatcher picks the Event and dispatches it to the configured lambda or the service URL as an HTTP POST request. The lambda reacts to the received Event.

Event publishing

1. The external application integrated with Kyma makes a REST API request to the Application Connector's Events Gateway to indicate that a new Event is available. The request provides the Application Connector with the Event metadata.

2. The Application Connector enriches the Event with the details of its source.

   NOTE: There is always one dedicated instance of the Application Connector for every instance of an external solution connected to Kyma.

3. The Application Connector makes a REST API call to event-publish-service and sends the enriched Event.

4. event-publish-service makes the HTTP payload compatible with Knative and sends the Event to the relevant knative-channel service URL which is inferred based on source id, event type, and event type version parameters.
5. Kubernetes service forwards the Event to the nats-dispatcher service served by the nats-dispatcher Pod.
6. nats-dispatcher saves the Event in NATS Streaming which stores the Event details in the Persistence storage volume.

Event validation

subscription-controller checks if the Namespace can receive Events from the application. It performs the check for each Kyma Subscription created in a Namespace for a particular Event type with a version for a specific application.

Validation flow

See the diagram and a step-by-step description of the Event verification process.

1. The Kyma user defines a lambda or a service.
2. The Kyma user creates a Subscription custom resource.
3. subscription-controller reads the new Subscription.
4. subscription-controller reads the EventActivation CR to verify if it exists in the Namespace for a certain application.
5. subscription-controller updates the Subscription resource accordingly with the activation status true or false. The Event Bus uses this status to allow or prohibit Event delivery.

Overview

The Event Bus ensures a successful flow of Events in Kyma when:

• You have enabled the EventActivation controller.
• You have created a Subscription custom resource and registered the webhook for a lambda or service to consume the Events.
• The Events are published.

Create the EventActivation controller

Enable the EventActivation controller to ensure the Event flow between the Namespace and the Application (App). Alternatively, bind the App to the Namespace and create a Service Instance.

The diagram shows you the Event activation flow for a given Namespace.

• The App sends the Events to the Event Bus and uses the EventApplication controller to ensure the Namespace receives the Events.
• If you define a lambda in the prod123 Namespace, it receives the order.created Event from the App through the Event Bus.
• The lambda in the test123 Namespace does not receive any Events since you have not enabled the EventActivation controller.

Create Subscription

Configure lambdas and services to use the push command for consuming Events coming from the App. To make sure the lambda or the service receive the Events, register a webhook for them by creating a Subscription custom resource.

Publish Events

Make sure that the external solution sends Events to Kyma. For details of the Event flow, see this document.

Events are delivered as HTTP POST requests. The Event metadata is a part of an HTTP request headers, whereas the Event payload is the body of the request.

The Event delivery workflow is as follows:

1. An external system uses the bound Application to publish an Event to the Event Bus.
2. The Event Bus checks for the Event subscription and activation. It creates a POST request using Event payload and metadata.
3. The service receives the POST request. The HTTP request headers represent Event metadata and HTTP request body represents the Event payload.

Event metadata

The following HTTP headers provide information about the Event metadata. The headers follow the format defined in the CloudEvents specification.

Event payload

The Event payload is delivered as the body of the HTTP Request in JSON format. The JSON schema is available in the Service Catalog in the registered service for the remote Events.

This example shows the order.created Event published by the external solution service:

{
  "example": {
    "orderCode": "4caad296-e0c5-491e-98ac-0ed118f9474e"
  },
  "properties": {
    "orderCode": {
      "description": "Resource identifier",
      "title": "OrderCode",
      "type": "string"
    }
  },
  "type": "object"
}

The HTTP POST request payload is a JSON object:

{"orderCode": "4caad296-e0c5-491e-98ac-0ed118f9474e"}

Responses

The service's HTTP response status code 2xx means that the message was successfully delivered to the subscriber. For example:

{
    "event-id": "22ae22a4-f5b7-4fa1-ada9-558a10a96f3d",
    "status": "published",
    "reason": "Message successfully published to the channel"
}

If the status code is not 2xx (< 200 or >= 300), it means that the delivery was unsuccessful and that the Event Bus will try to deliver it again. This implies At-least-once delivery guarantee.

If there were no subscriptions or consumers to this event-type, the message is ignored and the response will look like this:

{
    "event-id": "22ae22a4-f5b7-4fa1-ada9-558a10a96f3d",
    "status": "ignored",
    "reason": "Event was ignored as there are no subscriptions or consumers configured for this event"
}

Event Subscription service example

See this example to find a complete scenario for implementing a subscriber service to a business Event.

Overview

Knative Eventing Mesh leverages Knative Eventing components to build an eventing mesh that provides event routing and pub/sub capabilities. It abstracts the underlying messaging system and allows you to configure different persistence for each Namespace. Kyma components wire the mesh dynamically for event routing. This way, senders can inject Events into the mesh from multiple source points, and subscribers can receive Events based on filters and their access permissions. The Knative Broker and Trigger CRDs allow the process of Event publishing and consumption to run smoother, thus significantly improving the overall performance.

NOTE: Knative Eventing Mesh is available in the alpha version. Use it only for testing purposes.

The new Eventing Mesh runs in parallel with the existing Event Bus. The Kyma Event Bus still supports sending Events to the regular eventing endpoint, while a separate Kyma endpoint handles sending Events to the new Knative Eventing Mesh.

Event Flow

Send Events

The diagram shows you the main stages of the Event flow - from the moment the external Application sends it, up to the point when the lambda function receives it.

NOTE: The flow assumes you have already added a service instance of an external Application to your Namespace in the Kyma Console and created a lambda with an Event trigger.

1. The Application sends Events to the HTTP source adapter which is an HTTP server deployed inside the kyma-integration Namespace.

2. The HTTP source adapter forwards the Events to the default Knative Broker.

3. The Knative Broker then delivers Events to the proper lambda function.

Subscribe to Events

In the new Knative Eventing Mesh, you can use Knative Triggers to subscribe to any Events delivered to the Broker located in your Namespace.

You can also use expressions that allow the Trigger to filter the incoming Events. For details on setting filters, read the Trigger filtering section in this document.

Test Knative Eventing Mesh

To reach the new Eventing Mesh, use an HTTP request with the /events path. For example, if you have used gateway.example.cx/v1/events so far, use gateway.example.cx/events to make sure you work with the new Eventing Mesh.

NOTE: The HTTP source adapter only accepts Events compliant with the CloudEvents 1.0 specification.

Channel implementations

By default, Kyma comes with NatssChannel, however, Knative eventing allows you to change the default channel implementation or even use multiple channels simultaneously. You can override the default channel implementation during installation like this:

cat << EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: knative-eventing-overrides
  namespace: kyma-installer
  labels:
    installer: overrides
    component: knative-eventing
    kyma-project.io/installation: ""
data:
  knative-eventing.channel.default.apiVersion: knativekafka.kyma-project.io/v1alpha1
  knative-eventing.channel.default.kind: KafkaChannel
EOF

In this example, the default channel is set to Kafka.

Kafka

You can use a Knative-compatible Kafka channel implementation. The following section explains you how to configure the connection between Kyma and your Kafka cluster and how to install Kyma with the Kafka-Channel controller.

NOTE: Kafka Channel integration is in alpha version. Use it only for testing purposes.

The Knative-channel implementation supports the following providers. Use the links to set up a Kafka cluster.

• Azure Event Hubs
• Confluent Cloud
• Standard Kafka installation with no special authorization required

Before starting the Kyma installation, configure the connection between Kyma and the Kafka cluster. To do so, use the installation override:

export kafkaBrokers={todo user}
export kafkaNamespace={todo user}
export kafkaPassword={todo user}
export kafkaUsername={todo user}
export kafkaProvider={local|azure|confluent}
cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: knative-kafka-overrides
  namespace: kyma-installer
  labels:
    installer: overrides
    component: knative-eventing-channel-kafka
    kyma-project.io/installation: ""
type: Opaque    
stringData:
  kafka.brokers: $kafkaBrokers
  kafka.namespace: $kafkaNamespace
  kafka.password: $kafkaPassword
  kafka.username: $kafkaUsername
  kafka.secretName: knative-kafka
  environment.kafkaProvider: $kafkaProvider
EOF

NOTE: For additional values, see this file.

Once the installation has been customized, you can trigger the Kyma installation. You can install Kyma with a knative-eventing-channel-kafka custom component by following these instructions. The TestDefinition for the component is knative-eventing-channel-kafka-test.

Overview

Kyma comes with NATS Streaming as its default Channel. You can see the configuration details in the default-ch-webhook ConfigMap.

You can use a different messaging middleware, other than NATS Streaming, as the Kyma eventing operator. To achieve that:

• Apply the Channel Resources for the messaging middleware you want to use. These resources connect with the running messaging middleware.
• Configure the default-ch-webhook ConfigMap in the knative-eventing Namespace to use that particular Channel.

If you want to edit the default-ch-webhook ConfigMap, run:

kubectl -n knative-eventing edit configmaps default-ch-webhook

Read about the examples and the configuration details.

In-memory channel

Follow this guide to add the InMemoryChannel resources. This will deploy the InMemoryChannel CRD, Controller, and Dispatcher.

NOTE: Before installing this provisioner, add the following annotation to the podTemplate.Spec in the in-memory-channel-controller Deployment to remove the Istio sidecar.

template:
  annotations:
    sidecar.istio.io/inject: "false"
    metadata:
      labels: *labels

You can change the default channel configuration by editing the ConfigMap default-ch-webhook in knative-eventing Namespace. For example, if you want to set In-Memory Channels as default provisioner, include the following data in the ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: default-ch-webhook
  namespace: knative-eventing
data:
  default-ch-config: |
    clusterDefault:
      apiVersion: messaging.knative.dev/v1alpha1
      kind: InMemoryChannel
    namespaceDefaults:
      some-namespace:
        apiVersion: messaging.knative.dev/v1alpha1
        kind: InMemoryChannel

NOTE: This ConfigMap may specify a cluster-wide default channel and/or namespace-specific channel implementations.

Google PubSub

Follow this guide to install GCP PubSub Channel resources. This will apply the GCP PubSub Channel CRDs and deploy the cloud-run-events-controller controller.

Edit the default-ch-webhook ConfigMap located in the knative-eventing Namespace to include the following data.

apiVersion: v1
kind: ConfigMap
metadata:
  name: default-ch-webhook
  namespace: knative-eventing
data:
  default-ch-config: |
    clusterDefault:
      apiVersion: messaging.cloud.run/v1alpha1
      kind: Channel
      spec:
        project: <GCP Project Name>

NOTE: You need to mention the GCP Project Name in the specification which will be used as the reference GCP project to create GCP PubSub Topics.

To configure NATS Streaming chart, override the default values of its values.yaml file. This document describes parameters that you can configure.

TIP: To learn more about how to use overrides in Kyma, see the following documents:

• Helm overrides for Kyma installation
• Top-level charts overrides

Configurable parameters

This table lists the configurable parameters, their descriptions, and default values:

Management of the Event Bus is based on the custom resources specifically defined for Kyma. Manage all of these resources through kubectl.

Details

This section describes the resource names to use in kubectl, the command syntax, and examples of use.

Resource types

Event Bus operations use the following resources:

Syntax

Follow the kubectl syntax, kubectl {command} {type} {name} {flags}, where:

• {command} is any command, such as describe.
• {type} is a resource type, such as clusterserviceclass.
• {name} is the name of a given resource type. Use {name} to make the command return the details of a given resource.
• {flags} specifies the scope of the information. For example, use flags to define the Namespace from which to get the information.

Examples

The following examples show how to create new Subscriptions, list them, and obtain detailed information on their statuses.

• Create a new Subscription directly from the terminal:

  Click to copy

  cat <<EOF | kubectl create -f -
  apiVersion: eventing.kyma-project.io/v1alpha1
  kind: Subscription
  metadata:
    name: my-subscription
    namespace: stage
  spec:
    endpoint: http://testjs.default:8080/
    include_subscription_name_header: true
    event_type: order_created
    event_type_version: v1
    source_id: stage.commerce.kyma.local
  EOF

• Get the list of all Subscriptions:

  Click to copy

  kubectl get subscription --all-namespaces

• Get the list of all Subscriptions with detailed information on the Subscription status:

  Click to copy

  kubectl get subscriptions -n stage -o=custom-columns=NAME:.metadata.name,STATUS:.status.conditions[*].status,STATUS\ TYPE:.status.conditions[*].type

The tracing functionality available in Kyma can help you to pinpoint the root cause of an error and solve the problem. See this document to learn more about tracing.

No microservice or lambda configured to receive an Event

In this case, an external system sends the Event, but a lambda or microservice with an Event trigger does not exist.

As a result, you can see traces for publish only. When you access the trace details, they only show you tags for event-publish-service.

Configured microservice or lambda returns an error

In this case, a microservice or lambda exists and reacts to the Event trigger. However, due to a code issue, the microservice or lambda fails to process the Event.

As a result, the webhook, push, and name-of-lambda services in the trace are marked with error.

To see the error details, click one of the service spans, such as the one for the push service.

Since the Event Bus keeps on retrying to deliver the Event until it is successful, you can see multiple spans for webhook-service.