Eventing

Overview

Eventing in Kyma allows you to easily integrate external applications. Under the hood, Eventing implements NATS to ensure Kyma receives business events from external sources and is able to trigger business flows using Functions or services. NATS provides an abstraction layer where data is encoded and framed as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers.

To learn more about how to use Eventing, try the Trigger a Function with an event and Trigger the microservice with an event tutorials.

Architecture

Eventing uses NATS to implement the Event Publisher Proxy and the Eventing Controller which work together to process and deliver events in Kyma.

Event Publisher Proxy

The Event Publisher Proxy component receives legacy and Cloud Event publishing requests from the cluster workloads (microservices or Functions) and redirects them to the NATS server. It also fetches a list of subscriptions for a connected application.

Eventing Controller

The Eventing Controller component manages the internal infrastructure in order to receive an event. The Controller watches Subscription Custom Resource Definitions. When an event is received in an Application, it lays down the Eventing infrastructure in NATS in order to trigger a Function. The Eventing Controller also dispatches messages to subscribers such as a Function or another workload.

Event types

Eventing supports both Cloud Events and legacy events. Kyma converts legacy events to Cloud Events and adds the sap.kyma.custom prefix.

For a Subscription Custom Resource, the fully qualified event type takes the form of sap.kyma.custom.commerce.order.created.v1 or sap.kyma.custom.commerce.Account.Root.Created.v1. The event type is composed of the following components:

  • Prefix: sap.kyma.custom
  • Application: commerce
  • Event: can have two or more segments separated by . (For example, order.created or Account.Root.Created)
  • Version: v1

For publishers, the event type takes this form:

  • order.created or Account.Root.Created for legacy events coming from the commerce application
  • sap.kyma.custom.commerce.order.created.v1 or sap.kyma.custom.commerce.AccountRoot.Created.v1 for Cloud Events.

NOTE: In case the event contains more than two segments, Kyma Eventing will combine them into two segments when creating the underlying Eventing infrastructure (For example, Account.Root.Created will become AccountRoot.Created).

Details

Event processing and delivery

The event processing and delivery flow uses the NATS server to process events and send them to subscribers. This diagram explains the event flow in Kyma, from the moment the Application sends an event, to the point when the event triggers the Function.

Eventing flow

  1. The Eventing Controller watches the Subscription Custom Resource. It determines if there are any new incoming events.

  2. The Eventing Controller creates an infrastructure for the NATS server.

  3. The Application Connector publishes events to the Event Publisher Proxy.

  4. The Event Publisher Proxy sends events to the NATS server.

  5. The NATS server dispatches events to the Eventing Controller.

  6. The Eventing Controller dispatches events to subscribers (microservices or Functions).

In-cluster eventing

In-cluster Eventing allows publishers to send messages and subscribers to receive them without the need for a Kyma Application. This means that instead of the usual event flow where Application Connector publishes events to the Event Publisher Proxy, events can be published from within the cluster directly to the Event Publisher Proxy.

To use in-cluster Eventing, create a subscription where the eventType.value field includes the name of your application. In this example, this is sap.kyma.custom.nonexistingapp.order.created.v1, where nonexistingapp is an application that does not exist in Kyma.

Click to copy
apiVersion: eventing.kyma-project.io/v1alpha1
kind: Subscription
metadata:
name: mysub
namespace: mynamespace
spec:
filter:
filters:
- eventSource:
property: source
type: exact
value: ""
eventType:
property: type
type: exact
value: sap.kyma.custom.nonexistingapp.order.created.v1
protocol: ""
protocolsettings: {}
sink: http://myservice.mynamespace.svc.cluster.local

On the publisher side, you need to include the exact same Application name in the type field, like in this example:

Click to copy
curl -k -i \
--data @<(cat <<EOF
{
"source": "kyma",
"specversion": "1.0",
"eventtypeversion": "v1",
"data": {"orderCode":"3211213"},
"datacontenttype": "application/json",
"id": "759815c3-b142-48f2-bf18-c6502dc0998f",
"type": "sap.kyma.custom.nonexistingapp.order.created.v1"
}
EOF
) \
-H "Content-Type: application/cloudevents+json" \
"http://eventing-event-publisher-proxy.kyma-system/publish"

Custom Resource

Subscription

The Subscription CustomResourceDefinition (CRD) is used to subscribe to events. To get the up-to-date CRD and show the output in the YAML format, run this command:

kubectl get crd subscriptions.eventing.kyma-project.io -o yaml

Sample custom resource

This sample Subscription resource subscribes to an event called sap.kyma.custom.commerce.order.created.v1.

NOTE: Both the subscriber and the Subscription should exist in the same Namespace.

Click to copy
apiVersion: eventing.kyma-project.io/v1alpha1
kind: Subscription
metadata:
name: test
namespace: test
spec:
filter:
filters:
- eventSource:
property: source
type: exact
value: ""
eventType:
property: type
type: exact
value: sap.kyma.custom.commerce.order.created.v1
protocol: ""
protocolsettings: {}
sink: http://test.test.svc.cluster.local

Custom resource parameters

This table lists all the possible parameters of a given resource together with their descriptions:

ParameterRequiredDescription
metadata.nameYesSpecifies the name of the CR.
metadata.namespaceNoDefines the Namespace in which the CR is available. It is set to default unless your specify otherwise.
spec.filterYesDefines the list of filters.
spec.filter.dialectNoSpecifies the preferred Eventing backend. Currently, the capability to switch between Eventing backends is not available. It is set to NATS by default.
spec.filter.filtersYesDefines the filter element as a combination of two Cloud Event filter elements.
spec.filter.filters.eventSourceYesThe origin from which events are published.
spec.filter.filters.eventTypeYesThe type of events used to trigger workloads.
spec.filter.filters.eventSource.propertyYesMust be set to source.
spec.filter.filters.eventSource.typeNoMust be set to exact.
spec.filter.filters.eventSource.valueYesMust be set to "" for the NATS backend.
spec.filter.filters.eventType.propertyYesMust be set to type.
spec.filter.filters.eventType.typeNoMust be set to exact.
spec.filter.filters.eventType.valueYesName of the event being subscribed to, for example: sap.kyma.custom.commerce.order.created.v1.
spec.protocolYesMust be set to "".
spec.protocolsettingsYesDefines the Cloud Event protocol setting specification implementation. Must be set to {}.
spec.sinkYesSpecifies the HTTP endpoint where matching events should be sent to, for example: test.test.svc.cluster.local.

These components use this CR:

ComponentDescription
Eventing ControllerThe Eventing Controller reconciles on Subscriptions and creates a connection between subscribers and the Eventing backend.
Event Publisher ProxyThe Event Publisher Proxy reads the Subscriptions to find out how events are used for each Application.