CloudEvents Basics

I talked about CloudEvents in the context of event-driven architectures before. In this post, let’s explore CloudEvents in more depth.

CloudEvents: Why? What?

CloudEvents Logo

CloudEvents is a popular specification for describing event data in a common way with the goal of increasing interoperability between different event systems.

Google Cloud’s Eventarc, open-source Knative, Azure’s Event Grid, and many more projects rely on CloudEvent specification to define their event formats.

CloudEvents, at its core, defines a set of metadata, called “context attributes”. This metadata is the minimal set of information needed to route an event to the proper component. Data that is not intended for routing is placed within the data (or base64 encoded data_base64) field of CloudEvent.

What does a CloudEvent look like?

Depends on the content-mode being used but two main formats look like this.

Binary-mode:

curl localhost:8080 -v \
  -X POST \
  -H "Content-Type: application/json" \
  -H "ce-specversion: 1.0" \
  -H "ce-type: com.mycompany.myapp.myservice.myevent" \
  -H "ce-source: myservice/mysource" \
  -H "ce-id: 1234-5678" \
  -H "ce-time: 2023-01-02T12:34:56.789Z" \
  -H "ce-subject: my-important-subject" \
  -H "ce-extensionattr1: value" \
  -H "ce-extensionattr2: 5" \
  -d '{
        "foo1": "bar1",
        "foo2": "bar2"
      }'

Structured-mode:

curl localhost:8080 -v \
  -X POST \
  -H "Content-Type: application/cloudevents+json" \
  -d '{
        "specversion": "1.0",
        "type": "com.mycompany.myapp.myservice.myevent",
        "source": "myservice/mysource",
        "id": "1234-5678",
        "time": "2023-01-02T12:34:56.789Z",
        "subject": "my-important-subject",
        "datacontenttype": "application/json",
        "extensionattr1" : "value",
        "extensionattr2" : 5,
        "data": {
          "foo1": "bar1",
          "foo2": "bar2"
        }
      }'

CloudEvent Attributes

Core attributes are defined by the spec.

Required:

  • specversion
  • id
  • source
  • type

Optional:

  • subject
  • time
  • datacontenttype
  • dataschema

Extension attributes are additional optional metadata to help proper routing and processing of the CloudEvent. Some known extensions are documented.

Content Modes

There are 3 content modes in CloudEvents:

  • Binary-mode: The event data is stored in the message body, and event attributes are stored as part of message metadata. Allows for efficient transfer and without transcoding effort. Good for supporting receivers that might not be aware of CloudEvents as the metadata can be ignored.
  • Structured-mode: Keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing hops, and across multiple protocols.
  • Batch-mode: Multiple (zero or more) events are encoded in a single message body, according to a specific event format.

Batch-mode is not supported in all protocol/SDK combinations. For example, Javascript SDK supports HTTP and Kafka batch mode but not MQTT batch mode.

Event Formats

Defines how the CloudEvent is serialized:

  • JSON
  • Protobuf
  • Avro
  • XML (draft)

Not all event formats are supported in each SDK. JSON is the most supported one. For example, Javascript SDK supports JSON but not Avro or Protobuf.

Protocol Bindings

Defines how the CloudEvent is bound to an application protocol’s transport frame:

  • HTTP
  • AMQP
  • Kafka
  • MQTT
  • NATS
  • WebSockets (draft)

Not all protocol bindings are supported in each SDK. HTTP is the most supported one. For example, Javascript SDK supports HTTP and Kafka but not AMQP, MQTT, NATS

SDKs

There are CloudEvents SDKs to read and write CloudEvents in various languages:

Google CloudEvents and libraries

This repository contains types for CloudEvents issued by Google:

Google CloudEvent Type Libraries help parse the data field of CloudEvents into Google Events:

Eventarc uses CloudEvents for all of its events.

Upcoming specs

These are works-in-progress specs:

  • Discovery API
  • Subscriptions API
  • Schema Registry

Samples

Some samples to show how to read CloudEvents:

  • hello-cloudevents
    • A minimal CloudEvents triggered service using C# CloudEvents SDK.
  • hello-cloudevents-gcs
    • A Google Cloud Storage CloudEvents triggered service using C# CloudEvents SDK and Google CloudEvent Type Library.

References

Some useful references:

CloudEvents  Eventarc  Event-driven 

See also