CloudEvents Binding for CDEvents

CloudEvents Binding for CDEvents

Note: This is an unreleased, work-in-progress version of the spec, and is being worked on by members of the CDEvents project. You are very welcome to join the work and the discussions!

Abstract

The CloudEvents Binding for CDEvents defines how CDEvents are mapped to CloudEvents headers and body.

Table Of Contents

CloudEvents Context

The CloudEvents context is built by the event producer using some of the data from the CDEvents context.

specversion

The CloudEvents specversion MUST be set to 1.0.

id

The CloudEvents id MUST be set to the CDEvents id.

source

The CloudEvents source MUST be set to the CDEvents source.

type

The CloudEvents type MUST be set to the type of the CDEvent.

subject

The CloudEvents subject MUST be set to the subject id of the CDEvent. Note: since the subject is mandatory in CDEvents, the subject in the CloudEvents format will always be set - even if it’s not mandated by the CloudEvents specification.

time

The CloudEvents time MUST be set to the timestamp of the CDEvent. The CloudEvents specification allows for time to be set to either the current time or the time of the occurrence, but it requires all producers to be chose the same option. CDEvents requires all producers to use the timestamp from the CDEvent to meet the CloudEvents specification.

datacontenttype

The CloudEvents datacontenttype is optional, its use depends on the specific CloudEvents binding and mode in use. See the event data section for more details.

dataschema

The CloudEvents dataschema is MAY be set to a URL that points to the event data schema included in this specification.

CloudEvents Data

The content and format of the event data depends on the specific CloudEvents binding in use. All the examples, unless otherwise stated, refer to theHTTP binding in binary content mode. In this format, the CloudEvents context is stored in HTTP headers.

The CloudEvents Event Data MUST include the full CDEvents, i.e. context, subject and any custom data, rendered as JSON in the format specified by the schema for the event type.

Custom data of type “application/json” MUST be embedded as is in the customData field. Data with any other content-type MUST be base64 encoded and set as value for the customData field.

In CloudEvents HTTP binary mode, the Content-Type HTTP header MUST be set to application/json. In CloudEvents HTTP structured mode, the same information is carried in the CloudEvents context field datacontenttype.

Examples

Full example of a CDEvents transported through a CloudEvent in HTTP binary mode:

POST /sink HTTP/1.1
Host: cdevents.example.com
ce-specversion: 1.0
ce-type: dev.cdevents.taskrun.started
ce-time: 2018-04-05T17:31:00Z
ce-id: A234-1234-1234
ce-source: /staging/tekton/
ce-subject: /namespace/taskrun-123
Content-Type: application/json; charset=utf-8
Content-Length: nnnn

{
   "context": {
      "version" : "draft",
      "id" : "A234-1234-1234",
      "source" : "/staging/tekton/",
      "type" : "dev.cdevents.taskrun.started",
      "timestamp" : "2018-04-05T17:31:00Z",
   }
   "subject" : {
      "id": "/namespace/taskrun-123",
      "type": "taskRun",
      "content": {
         "task": "my-task",
         "url": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/my-taskrun-123"
         "pipelineRun": {
            "id": "/somewherelse/pipelinerun-123",
            "source": "/staging/jenkins/"
         }
      }
   }
}