Add docs about cloud events structure

Add headers the payload format for cloud events generated by Tekton Signed-off-by: Andrea Frittoli <andrea.frittoli@uk.ibm.com>
tektoncd · Feb 5, 2021 · 7827cd8 · 7827cd8
1 parent 4328fce
commit 7827cd8
Showing 1 changed file with 126 additions and 0 deletions.
diff --git a/docs/events.md b/docs/events.md
@@ -68,3 +68,129 @@ Resource      |Event    |Event Type
 `PipelineRun` | `Condition Change while Running` | `dev.tekton.event.pipelinerun.unknown.v1`
 `PipelineRun` | `Succeed` | `dev.tekton.event.pipelinerun.successful.v1`
 `PipelineRun` | `Failed`  | `dev.tekton.event.pipelinerun.failed.v1`
+
+## Format of `CloudEvents`
+
+According to the [`CloudEvents` spec](https://github.com/cloudevents/spec/blob/master/spec.md), HTTP headers are included to match the context fields. For example:
+
+```
+"Ce-Id": "77f78ae7-ff6d-4e39-9d05-b9a0b7850527",
+"Ce-Source": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/curl-run-6gplk",
+"Ce-Specversion": "1.0",
+"Ce-Subject": "curl-run-6gplk",
+"Ce-Time": "2021-01-29T14:47:58.157819Z",
+"Ce-Type": "dev.tekton.event.taskrun.unknown.v1",
+```
+
+Other HTTP headers are:
+```
+"Accept-Encoding": "gzip",
+"Connection": "close",
+"Content-Length": "3519",
+"Content-Type": "application/json",
+"User-Agent": "Go-http-client/1.1"
+```
+
+The payload is JSON, a map with a single root key `taskRun` or `pipelineRun`, depending on the source
+of the event. Inside the root key, the whole `spec` and `status` of the resource is included. For example:
+
+```json
+{
+  "taskRun": {
+    "metadata": {
+      "annotations": {
+        "pipeline.tekton.dev/release": "v0.20.1",
+        "tekton.dev/pipelines.minVersion": "0.12.1",
+        "tekton.dev/tags": "search"
+      },
+      "creationTimestamp": "2021-01-29T14:47:57Z",
+      "generateName": "curl-run-",
+      "generation": 1,
+      "labels": {
+        "app.kubernetes.io/managed-by": "tekton-pipelines",
+        "app.kubernetes.io/version": "0.1",
+        "tekton.dev/task": "curl"
+      },
+      "managedFields": "(...)",
+      "name": "curl-run-6gplk",
+      "namespace": "default",
+      "resourceVersion": "156770",
+      "selfLink": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/curl-run-6gplk",
+      "uid": "4ccb4f01-3ecc-4eb4-87e1-76f04efeee5c"
+    },
+    "spec": {
+      "params": [
+        {
+          "name": "url",
+          "value": "https://api.hub.tekton.dev/resource/96"
+        }
+      ],
+      "resources": {},
+      "serviceAccountName": "default",
+      "taskRef": {
+        "kind": "Task",
+        "name": "curl"
+      },
+      "timeout": "1h0m0s"
+    },
+    "status": {
+      "conditions": [
+        {
+          "lastTransitionTime": "2021-01-29T14:47:58Z",
+          "message": "pod status \"Initialized\":\"False\"; message: \"containers with incomplete status: [place-tools]\"",
+          "reason": "Pending",
+          "status": "Unknown",
+          "type": "Succeeded"
+        }
+      ],
+      "podName": "curl-run-6gplk-pod-rsgn2",
+      "startTime": "2021-01-29T14:47:57Z",
+      "steps": [
+        {
+          "container": "step-curl",
+          "name": "curl",
+          "waiting": {
+            "reason": "PodInitializing"
+          }
+        }
+      ],
+      "taskSpec": {
+        "description": "This task performs curl operation to transfer data from internet.",
+        "params": [
+          {
+            "description": "URL to curl'ed",
+            "name": "url",
+            "type": "string"
+          },
+          {
+            "default": [],
+            "description": "options of url",
+            "name": "options",
+            "type": "array"
+          },
+          {
+            "default": "docker.io/curlimages/curl:7.72.0@sha256:3c3ff0c379abb1150bb586c7d55848ed4dcde4a6486b6f37d6815aed569332fe",
+            "description": "option of curl image",
+            "name": "curl-image",
+            "type": "string"
+          }
+        ],
+        "steps": [
+          {
+            "args": [
+              "$(params.options[*])",
+              "$(params.url)"
+            ],
+            "command": [
+              "curl"
+            ],
+            "image": "$(params.curl-image)",
+            "name": "curl",
+            "resources": {}
+          }
+        ]
+      }
+    }
+  }
+}
+```