This repository contains information, references, and samples about CloudEvents.
CloudEvents is a 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 the
request to the proper component. Data that is not intended for routing is placed
within the data (or base64 encoded data_base64) field of CloudEvent.
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"
}
}'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.
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.
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.
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
There are CloudEvents SDKs to read and write CloudEvents in various languages:
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.
These are works-in-progress specs:
- Discovery API
- Subscriptions API
- Schema Registry
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.
Useful links:
Talks:
- CloudEvents: Intro, Deep-Dive - Doug Davis, Clemens Vasters, Klaus Deissner & Vladimir Bacvanski
- CloudEvents: Intro, Status and the Future - Scott Nichols
- CloudEvents And Beyond! - Doug Davis
This is not an official Google product.