Knative Eventing Documentation

Knative Eventing is a Kubernetes-based platform designed for reliable, secure, and scalable asynchronous event delivery. It enables developers to build event-driven applications by providing a consistent way to deliver events from both packaged sources and custom application-created sources to consumers located both on-cluster and off-cluster.

The platform focuses on three core pillars:

1. Developer Experience: Provides a uniform experience for sourcing, consuming, and creating events by leveraging the CloudEvents standard. This allows developers to treat internal and external event sources identically.
2. Event Delivery: Offers a pluggable event delivery infrastructure based on a well-documented specification and conformance tests. This pluggable architecture allows operators to choose the specific delivery substrate that meets their requirements.
3. Event Sourcing: Provides specifications and tools for creating event sources, ensuring that event providers can integrate cleanly into a CloudEvents-compliant environment.

The Knative Eventing configuration is organized into functional groups. When managing or inspecting the configuration, you can navigate through these primary directories:

• core/: Contains the essential elements required for Knative Eventing to function.
• channels/: Contains reference implementations of the Channel abstraction.
• brokers/: Contains reference implementations of the Broker abstraction.
• monitoring/: An installable bundle of tooling for observability functions.
• *.yaml: Symlinks representing specific "rendered views" of the configuration.

Within the core/ directory, the configuration is further subdivided:

• roles/: Cluster roles required for core controllers or for integration with standard Kubernetes RBAC.
• configmaps/: Configuration maps used to configure core components.
• resources/: Definitions for Knative Eventing resources.
• webhooks/: Configurations for mutating and validating admission webhooks and their supporting resources.
• deployments/: Executable components and their associated configuration resources.

Knative Eventing is a collection of APIs designed for building event-driven architectures on Kubernetes. It enables the routing of events from sources (producers) to sinks (consumers).

Key features include:

• CloudEvents Compliance: Uses standard HTTP requests following the CloudEvents specification, ensuring interoperability across different programming languages and systems.
• Loose Coupling: Producers and consumers can be developed and deployed independently. A producer can emit events before a consumer exists, and a consumer can subscribe to event classes before a producer is active.
• Workload Support: Supports various workloads, including standard Kubernetes Services and Knative Serving Services.
• Asynchronous Communication: Sinks can be configured to respond to HTTP requests by sending response events, facilitating asynchronous application development.
• Connectivity: Services can be connected to form new applications without modifying the original producer or consumer, allowing for fine-grained selection of event subsets.

An EventPolicy defines which sources are allowed to send events to which targets. It acts as an authorization layer for event ingress.

Spec Configuration

• from: A list of EventPolicySpecFrom defining allowed sources (either via a resource ref or an OIDC identity sub).
• to: A list of EventPolicySpecTo defining the target resources. If empty, the policy applies to all resources in the EventPolicies namespace.
• filters: An optional list of SubscriptionsAPIFilter expressions. An event must pass all filters to reach the target. If no filters are provided, all events are accepted.

Target Selection (spec.to)

You can target resources using:

• ref: A direct reference to a target resource (EventPolicyToReference).
• selector: A LabelSelector to group multiple targets.

Source Selection (spec.from)

You can define allowed sources using:

• ref: A direct reference to a resource (EventPolicyFromReference).
• sub: An OIDC identity name or a glob-like pattern to match suffixes.

In Knative Eventing, Channelable is a skeleton type used to represent resources that are both Subscribable (can receive events via subscriptions) and Addressable (have a reachable network address).

While Channelable is not a real resource itself, it is used by resource writers to define compatible resources. It is commonly used to deserialize Channelable ObjectReferences to access their subscription and address data.

A Channelable typically consists of:

• metadata: Standard Kubernetes ObjectMeta.
• spec: Contains SubscribableSpec (for subscription logic) and an optional delivery (DeliverySpec) which defines global default delivery settings for all subscriptions to this channel.
• status: Contains ChannelableStatus, which aggregates AddressStatus, SubscribableStatus (tracking subscribers), DeliveryStatus (resolved dead letter sinks), and AppliedEventPoliciesStatus.

The Channelable type is a skeleton type used by resource writers to embed both Subscribable and Addressable capabilities. It is typically used to deserialize Channelable ObjectReferences to access subscription and address data. Note that Channelable itself is not a real resource but a wrapper for compatibility.

Structure of Channelable:

• metadata: Kubernetes meta/v1.ObjectMeta.
• spec: A ChannelableSpec containing:
  • SubscribableSpec (embedded members).
  • delivery (Optional): A DeliverySpec for controlling event delivery.
• status: A ChannelableStatus containing:
  • Status: Inherits duck/v1.Status (includes ObservedGeneration and Conditions).
  • AddressStatus: Fulfills the Addressable contract.
  • SubscribableStatus: Fulfills the Subscribable contract (includes Subscribers status).
  • deadLetterChannel (Optional): A KReference set by the channel for native error handling. Failed messages are delivered here.

Knative Eventing supports several distinct user personas, each with different goals and interaction patterns with the system:

• Event Consumer (Developer/Integrator): Focuses on consuming events. They look for available event sources, trigger services based on event feeds, and filter events from providers. Integrators may use existing packaged functions to build workflows without writing code.
• Event Producer: Owns the data source or system generating events. They are responsible for publishing events and controlling who is authorized to create Feeds.
• System Integrator: Extends the Knative ecosystem by implementing new core components. They create new Event Sources (bridges between existing systems and Knative), Channels, or Brokers.
• System Operator: Manages the platform lifecycle. They handle the installation and upgrading of Knative Eventing and its CRDs (Sources, Broker Implementations), upgrade backing infrastructure (like Kafka or RabbitMQ), monitor system health, and manage developer access permissions.

Knative Eventing uses a multi-tenant scheduler to manage how eventing source instances (like KafkaSource) are distributed across Kubernetes resources.

Core Abstractions

• Virtual Pod (vpod): An abstraction representing an eventing source instance. A vpod can be scaled by adjusting its number of vreplicas (vreplicas). A vreplica corresponds to a specific resource in the source (e.g., a consumer in a Kafka consumer group).
• Placements: The mapping of vreplicas onto real Kubernetes pods. These placement details are stored in the eventing source's status field for observability.

Scheduling Logic

The scheduler takes a list of (source, # of vreplicas) tuples and computes Placements. It follows a strategy of allocating as many vreplicas as possible into the lowest possible StatefulSet ordinal number. This ensures efficient use of resources by filling lower-indexed pods before moving to higher ones.

To support this, the system relies on pods having a sticky identity (provided by StatefulSet replicas).

When using an EventTransform, you can define where transformed events are sent and how to handle responses from the destination (Sink).

Sink Configuration

• Sink (Optional): A reference to an object that resolves to a URI. This is the destination for the transformed event.
• Note: If Sink is not provided, the transformation sends the transformed event back as a response. This is useful for leveraging the built-in Broker reply feature to re-publish a transformed event back to the broker.

Reply Configuration

• reply (Optional): Configures how to handle responses from the Sink. This can only be set if Sink is also set.
• EventTransformations: Defines transformations to be applied to the responses from the Sink. The transformation type used in reply must match the top-level transformation type. To mix types, use compositions and chain transformations.
• discard (bool, Optional): If true, responses from the Sink are discarded and an empty response body is returned. If false (default), the exact Sink response body is returned. discard is mutually exclusive with EventTransformations in the reply section.