Keptn CloudEvents

Project
Service
Approval
Deployment
Rollback
Test
Evaluation
Release
Get-Action
Action
Get-SLI
Monitoring
Problem
Error Log

All Keptn events conform to the CloudEvents spec in version 1.0. The CloudEvents specification is a vendor-neutral specification for defining the format of event data.

In Keptn, events have a payload structure as follows (Note: The triggeredid is not contained in events of type triggered mentioned below):

"sh.keptn.event": {
  "required": [
    "data",
    "id",
    "shkeptncontext",
    "source",
    "specversion",
    "time",
    "triggeredid",
    "gitcommitid",
    "type"
  ],
  "properties": {
    "data": {
      "type": ["object", "string"],
      "description": "The Keptn event payload depending on the type."
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique UUID of the Keptn event"
    },
    "shkeptncontext": {
      "format": "uuid",
      "type": "string",
      "description": "Unique UUID value that connects various events together"
    },
    "source": {
      "format": "uri-reference",
      "type": "string",
      "minLength": 1,
      "description": "URL to service implementation in Keptn code repo"
    },
    "specversion": {
      "type": "string",
      "minLength": 1,
      "description": "The version of the CloudEvents specification",
      "value": "1.0"
    },
    "shkeptnspecversion": {
      "type": "string",
      "minLength": 1,
      "description": "The version of the Keptn specification",
      "value": "0.2.0"
    },
    "time": {
      "format": "date-time",
      "type": "string",
      "description": "Timestamp of when the event happened"
    },
    "triggeredid": {
      "format": "uuid",
      "type": "string",
      "description": "The event ID that has triggered the step"
    },
    "gitcommitid": {
      "format": "uuid",
      "type": "string",
      "description": "The git commit ID of the resource used in the context"
    },
    "type": {
      "type": "string",
      "minLength": 1,
      "description": "Type of the Keptn event"
    }
  },
  "additionalProperties": false,
  "type": "object"
}

Type

In Keptn, events follow two different formats of event types. One is related to the overall status of a task sequence execution, while the other format is related to the execution of a certain task within a sequence.

Task sequence events

The event type of a Keptn CloudEvent concerning the overall state of a task sequence has the following format:

sh.keptn.event.[stage].[task sequence].[event status] - For events concerning the execution of a task sequence

As indicated by the brackets, the event type is defined by a stage, task sequence and the event status.

The task sequence is declared in the Shipyard of a project.
The kinds of event states are defined with: triggered and finished

For example, if a task sequence with the name delivery in the stage hardening should be executed, it has to be triggered by sending an event with the type sh.keptn.event.hardening.delivery.triggered. Once the delivery sequence is completed, a sh.keptn.event.hardening.delivery.finished event will be sent to indicate the completion of the task sequence.

Task events

The event type of a Keptn CloudEvent concerning the execution of a certain task within a task sequence has the following format:

sh.keptn.event.[task].[event status] - For events concerning the execution of a certain task within a task sequence

As indicated by the brackets, the event type is defined by a task and the event status.

The task is declared in the Shipyard of a project. For example, a Shipyard can contain tasks like: deployment, test, or evaluation. Consequently, the event type for a deployment task would be sh.keptn.event.deployment.[event status]
The kinds of event states are defined with: triggered, started, status.changed, and finished (status.changed is optional)

By combining the task and event status for the deployment task, the event types are:

sh.keptn.event.deployment.triggered
sh.keptn.event.deployment.started
sh.keptn.event.deployment.status.changed
sh.keptn.event.deployment.finished

Standard vs. Custom Task Events

This page shows some standard task events such as deployment, test and evaluation. The Keptn project has chosen to define these as they are common "tasks" that DevOps and SRE practioners want to achieve.

The Shipyard file accepts any String as a task name: you are not limited to only the tasks shown on this page.

Keptn core will "translate" the task name to a cloudevent type and build that taskname.triggered event automatically for you.

For example, given this Shipyard:

...
tasks:
  - name: "my-custom-task"
...

Keptn would "automatically" translate that at runtime into a cloudevent like this:

{
  ...
  "type": "sh.keptn.event.my-custom-task.triggered"
  ...
}

All tasks have a lifecycle:

task.triggered
task.started
task.status.changed (optional)
task.finished

Any custom integrations must craft and send back these events such as task.started:

{
  ...
  "type": "sh.keptn.event.my-custom-task.started"
  ...
}

task.status.changed:

{
  ...
  "type": "sh.keptn.event.my-custom-task.status.changed"
  ...
}

And task.finished:

{
  ...
  "type": "sh.keptn.event.my-custom-task.started"
  ...
}

Data

The data block of a Keptn CloudEvent carries the Keptn Payload of a specific event and contains the properties:

labels
message
project
service
stage
status: indicates whether the service executing the task was able to perform the task without any unexpected errors. Possible values are succeeded, errored,or unknown
result: indicates the result of a successful task execution without unexpected problems (i.e. status = succeeded), such as the result of an evaluation, or a test execution. Possible values are pass, warning, or fail
[task]

Like the task property in the event type, the task property in the data block depends on the task declaration in the Shipyard. Based on the example of a deployment task, the data block contains a deployment property of type object. Hence, any payload can be added to this deployment property

In the following each data block is described and an example of a CloudEvent containing the data block is given.

Project

Project Create Triggered

Type

sh.keptn.event.project.create.triggered

Data Json Schema

Json Schema of sh.keptn.event.project.create.triggered

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "$ref": "#/definitions/ProjectCreateData",
  "definitions": {
    "ProjectCreateData": {
      "required": [
        "projectName",
        "shipyard"
      ],
      "properties": {
        "projectName": {
          "type": "string"
        },
        "gitRemoteURL": {
          "type": "string"
        },
        "shipyard": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "type": "object"
    }
  }
}

Example Cloud Event

{
  "specversion": "1.0",
  "id": "c4d3a334-6cb9-4e8c-a372-7e0b45942f53",
  "source": "source-service",
  "type": "sh.keptn.event.project.create.triggered",
  "datacontenttype": "application/json",
  "data": {
    "projectName": "sockshop",
    "gitRemoteURL": "https://github.com/project/repository",
    "shipyard": "c3RhZ2VzOg0KICAtIG5hbWU6ICJkZXYiDQogICAgZGVwbG95bWVudF9zdHJhdGVneTogImRpcmVjdCINCiAgICB0ZXN0X3N0cmF0ZWd5OiAiZnVuY3Rpb25hbCINCiAgLSBuYW1lOiAic3RhZ2luZyINCiAgICBkZXBsb3ltZW50X3N0cmF0ZWd5OiAiYmx1ZV9ncmVlbl9zZXJ2aWNlIg0KICAgIHRlc3Rfc3RyYXRlZ3k6ICJwZXJmb3JtYW5jZSINCiAgLSBuYW1lOiAicHJvZHVjdGlvbiINCiAgICBkZXBsb3ltZW50X3N0cmF0ZWd5OiAiYmx1ZV9ncmVlbl9zZXJ2aWNlIg0KICAgIHJlbWVkaWF0aW9uX3N0cmF0ZWd5OiAiYXV0b21hdGVkIg0K"
  },
  "shkeptncontext": "a3e5f16d-8888-4720-82c7-6995062905c1",
  "gitcommitid": "521747298a3790fde1710f3aa2d03b55020575aa"
}

Files

cloudevents.md

Latest commit

History

cloudevents.md

File metadata and controls

Keptn CloudEvents

Type

Task sequence events

Task events

Standard vs. Custom Task Events

Data

Project

Project Create Triggered

Type

Data Json Schema

Example Cloud Event

Project Create Started

Type

Data Json Schema

Example Cloud Event

Project Create Finished

Type

Data Json Schema

Example Cloud Event

Service

Service Create Started

Type

Data Json Schema

Example Cloud Event

Service Create Status Changed

Type

Data Json Schema

Example Cloud Event

Service Create Finished

Type

Data Json Schema

Example Cloud Event

Approval

Approval Triggered

Type

Data Json Schema

Example Cloud Event

Approval Started

Type

Data Json Schema

Example Cloud Event

Approval Status Changed

Type

Data Json Schema

Example Cloud Event

Approval Finished

Type

Data Json Schema

Example Cloud Event

Deployment

Deployment Triggered

Type

Data Json Schema

Example Cloud Event

Deployment Started

Type

Data Json Schema

Example Cloud Event

Deployment Status Changed

Type

Data Json Schema

Example Cloud Event

Deployment Finished

Type

Data Json Schema

Example Cloud Event

Rollback

Rollback Triggered

Type

Data Json Schema

Example Cloud Event

Rollback Started

Type

Data Json Schema