Skip to content

This repository contains information, references, and samples about CloudEvents.

License

Notifications You must be signed in to change notification settings

meteatamel/cloudevents-basics

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

17 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CloudEvents Basics

CloudEvents Logo

This repository contains information, references, and samples about CloudEvents.

CloudEvents: Why? What?

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.

What does a CloudEvent look like?

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

Useful links:

Talks:


This is not an official Google product.

About

This repository contains information, references, and samples about CloudEvents.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published