Skip to main content

Exposing Events

Optional Feature

Event support is an optional feature of the Control Plane. It must be explicitly enabled by a platform administrator through an EventConfig resource for each zone. If events are not enabled in your environment, you can skip this page.

Exposing an event is a two-step process. First, you register your event type specification so the platform knows about your event. Then, you declare the exposure in a Rover file to configure messaging and access control. Both steps are applied in the same way using roverctl apply.

Prerequisites

Your team must be onboarded before you can expose events. See Applications for details on how the platform identifies your team and application.

Step 1: Register Your Event Specification​

Before exposing an event, you must register its event type specification. This creates an EventType resource in the Control Plane, which serves as the central reference for your event's metadata.

The event specification is a dedicated resource with kind: EventSpecification. It defines the event type identifier, version, and an optional JSON schema describing the event payload.

eventspec.yaml
kind: EventSpecification
apiVersion: tcp.ei.telekom.de/v1
metadata:
  name: order-created-v1
spec:
  type: de.telekom.orders.created.v1
  version: '1.0.0'
  description: Events published when a new order is created
  specification: |
    {
      "$id": "https://example.com/order-created.schema.json",
      "$schema": "http://json-schema.org/draft-07/schema",
      "title": "OrderCreated",
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string",
          "description": "Unique identifier for the order."
        },
        "amount": {
          "type": "number",
          "description": "Total order amount."
        }
      }
    }

Apply the specification:

roverctl apply -f eventspec.yaml

Key Fields​

FieldDescription
typeA globally unique identifier for the event type. Lowercase letters and digits form nonempty segments separated by single dots or hyphens (e.g., de.telekom.orders-created.v1). It must end in .v<major>, matching the major number in version.
versionThe version of the event type specification.
descriptionA human-readable summary of what this event represents.
specificationAn optional JSON schema describing the event payload structure, either inline or as a file reference (see below).

Referencing a Schema File​

Instead of inlining the schema, specification can reference a local JSON file:

spec:
  specification:
    $ref: file://schemas/order-created.json

Relative paths can be resolved against two supported locations. roverctl first checks the directory of the resource file that contains the EventSpecification. Only if no file exists there, it checks the path relative to the configured resource path (RESOURCE_PATH / ROVER_RESOURCE_PATH), or relative to the current working directory when no resource path is set. The second location is only checked when the file is missing in the first. If the file exists but cannot be read or parsed, or the path is a directory, roverctl reports that error. Absolute paths (e.g. file:///abs/path/schema.json) are used as-is.

What Happens​

The EventSpecification handler processes your specification and creates an EventType resource. This resource stores the event's metadata and makes the event type discoverable in the platform.

Step 2: Expose the Event in Your Rover​

Once the event specification is registered, you can declare the exposure in your Rover file. The eventType in your exposure must match the type registered in Step 1.

rover.yaml
apiVersion: tcp.ei.telekom.de/v1
kind: Rover
metadata:
  name: order-service
spec:
  zone: dataplane1
  exposures:
    - type: event
      visibility: ENTERPRISE
      eventType: de.telekom.orders.created.v1
      approval: SIMPLE

Apply the Rover file:

roverctl apply -f rover.yaml

Key Fields​

FieldDescription
eventTypeThe event type identifier. Uses the same lowercase letter/digit segments and dot/hyphen separators as type; must match an existing EventType resource registered in Step 1.
approvalThe approval strategy for subscription requests: auto, simple, or foureyes. See Approvals.

What Happens​

When you apply the Rover file, the Control Plane:

  1. Creates an Application resource for your service (if it does not already exist)
  2. Creates an EventExposure linking your application to the EventType resource
  3. Checks that your event type is registered and prepares it for publishing and subscriptions
caution

If the EventType does not exist (i.e., the specification was not registered in Step 1), the EventExposure will remain in a pending state until the specification is applied.

The event type is now discoverable by other teams and ready to receive subscription requests.

Send events to the publish URL provided for your zone (/horizon/events/v1; /horizon/publish/v1 is also supported). Use the full provided URL, including any base path.

API & Event Features​

Beyond the basic event exposure, you can customize your event type with additional features such as publisher scopes and additional publisher IDs.

tip

See API & Event Features for the full list of features and detailed configuration examples.

FeatureDescription
Publisher ScopesDefine named scopes to partition your events and apply publisher-side filters. Subscribers can choose which scopes to receive.
Additional Publisher IDsAllow multiple applications to publish events to the same event type.

Next Steps​