---
tags: SIG Events, CDEvents
---

# Events Vocabulary

This is the terminology/vocabulary proposed by the 'Events in CD/CD' workstream within CDF SIG Interoperability

*This work is in progress*

## Sources
The proposal outlined in this document is inspired by existing event protocols, such as those used in e.g. Eiffel, Keptn and Tekton

## Top Level Terms
These terms are intended to be used as individual event types
- Activity Started
- Activity Finished
- Activity Canceled
- Activity Triggered
- Status Changed (informs e.g. about Y test cases executed or X canary releases performed)

## Activity types
In the world of Tekton: Pipeline, Task (part of the event type)
In the world of Eiffel: Activity
In the world of Keptn: Test, Deployment, Release, DB-Migration, etc.

## Event Details
Each event type can have various properties and they are defined in this section

### Activity Started
- URI (link to ongoing execution , e.g. Jenkins job)
- Live Logs (URI link(s) to ongoing execution)

### Activity Finished
- Outcome PASSED/FAILED
- Persistant Logs (URI link(s) to finished logs)

- Eiffel
- outcome.verdict=PASSED, FAILED, INCONCLUSIVE
- outcome.conclusion=SUCCESSFUL, FAILED, ABORTED, TIMED_OUT, INCONCLUSIVE

- Keptn
- result=pass, failed
- status=succeeded, errored, unknown

- Tekton
- https://github.com/tektoncd/pipeline/blob/master/docs/events.md#events-via-cloudevents
- dev.tekton.event.taskrun.started.v1

### Activity Canceled
- TBD

### Activity Triggered
- Activity Name

### Alerting/Monitoring/Still Processing
- URI (link to ongoing execution)

### Status Changed (informs e.g. about Y test cases executed or X canary releases performed)
- Context: Refers to the system on which the state is changed

## Events Categories

To discuss in the working group

- Build Pipeline Events
- Build Events
- Artifact Built Success
- Artifact Built Failed
- Test Events
- Unit Test Queued
- Unit Test Started
- Unit Test Succeded
- Unit Test Failed
- Integration Test Queued
- Integration Test Started
- Integration Test Succeded
- Integration Test Failed
- Security Related Events
- Artifact Scan Queued
- Artifact Scanned
- Release Events
- Artifact Released

- [NEW, to be discussed] Delivery Pipeline Events (for Continuous Delivery activities) (e.g. from Eiffel/ESCI)
- Composition (Eiffel)/ Baseline (ESCI) events
- Component Version Created (ESCI)
- Composition Defined (Eiffel) / Baseline Version Created (ESCI)
- Confidence Level Modified (Eiffel) / Confidence Label Result Changed (ESCI)
- Resource allocation events (ESCI)
- Resource Set Allocated
- Resource Set Deallocated
- Test Selection / Avoidance events (Eiffel)
- Test Execution Recipe Collection Created
- Activity Block events (ESCI)
- Activity Block Run Created
- Activity Block Run Started
- Activity Block Run Finished

- Deployment Pipeline Events (Related to an Environment)
- Service Deployed
- Service Upgraded
- Service Deleted

- Infrastructure Events
- Environment Events
- Environment Created
- Environment Deleted
- Runtime Events
- Service Status Changed (Up/Down/Error)
- Git repository Events
- PR Created Event
- PR Merged Event

## Suggestions and current solution
Current solutions
- [Events in Fedora](https://pagure.io/fedora-ci/messages/blob/master/f/schemas)
- [Eiffel](https://github.com/eiffel-community/eiffel/tree/master/eiffel-vocabulary)

Suggestions
- [Enterprise Scale CI](https://github.com/erkist/sig-interoperability/tree/erkist-esci/workstreams/events_in_cicd/input/enterprise-scale-ci)

## Event Structure

### Cloudevents
We suggest that the event protocol is based on [Cloudevents](https://github.com/cloudevents/spec)

## TODO for Events and Categories
- Define each event meaning to avoid overlapping and confusion, higher level first and then CloudEvents
- See [Event Definitions](#Event-Definitions)
- We will semantic decision about errors and kind failures
- Generic X-Finished event with status vs. separate events for different statuses (X-Succeded, X-Failed)
- Survey: create an initial proposal, then ask people about what they want to add or remove?

### Prescriptive or descriptive?
We suggest that events should always be descriptive, and never prescriptive, i.e. they should tell what has occured, not was is supposed to happen.
TODO: Check out if there is a definition of this on Cloudevents to link to.

## Decision Log

- Should the events be based on Cloudevents or should we define the whole message ourselves?
- Decided on Oct 12th: It should be based on Cloudevents.

## Discussion

### Event structure
- Should the event be "lightweight" with only the changes or should it be "complete" with all need information? I.e. with or without its 'context'
- Keptn has more or less a "complete" event
- Eiffel has more or less "lightweight"
- Tekton uses K8s CRDs, and the events contain the complete resource, spec and status. Tekton does not reference sources that can change over time.
- There are pros and cons with both
- Easier for the consumers if it is a 'complete' event
- The consumer could listen to all events and make sense of all events in combination
- \*This comment is valid for lighweight events
- We could allow both simplistic and complex
- Event id 'links' (an event id pointing at any historical event) between events could be used to follow events upstream in multiple levels. See [Events relations](/B-Z7mLh_Qc6frm51f3GIYA#Event-relations) below.
- Should the events be easy to send or easy to read?
- Relates to the "lightweight"/"complete" event discussion
- It would be best if it is easy for both. That could be accomplished if we allow both thin and thick events.
- Should we allow custom/convenience data in the protocol defined events or should it be easy to created your own events with required data?
- Some kind of custom data probably needs to be supported
- A drawback with allowing custom data to a predefined event would be that the parameters that are standardized in a new version could be conflicting (if the same property names are used for example)
- It is probably good if the custom data is at least isolated from the main parts of the protocol through namespacing or the like.
- As a system architect it would be best if the protocol was very strict as that would make it easier to make valid guesses on message sizes and such
- Adding custom data to an defined event type actually creates a 'secondary layer' of standardization between the producer and the intended consumer, but which is not defined in the actual protocol
- \*Including such convenience data in the event data schema will introduce complexities with it comes to updates of the event schemas, as two or more events will then be tied together schema wise.

### Why do we send events?
Should the events be sent to tell what has been done or should the events be sent to instruct what to do? I.e. descriptive or prescriptive (describing or commanding)
- Events should be used to tell what has been done
- RL: It could probably also be commanding
- E.g. commanding a down stream system to preform an action. E.g OpenShift/Rancher. Instead of the CD system sending an API request to those systems, the downstream systems can listen for an "action" or command. More geared towards platform creators / engineers. ['Contract first' vs 'contract last' API](https://stackoverflow.com/a/1899042/10717186).
- 'Commanding event API', where also the response should be sent as an event defined by this protocol
- AF: Webhooks can be seen as descriptive events. Kubernetes cronjobs will send commanding events to perform certain actions. So it could be both. All events should be assumed to be listened to by anyone and its up to the consumers to do what they want from them.
- If events are commanding and requests some kind of response from the consumer, you could end up in a situation where you're expecting a response but you don't know how long to wait as you might not know the characteristics of the consumer.
- \*Using asynchronous event sending in a prescriptive way, waiting for their results, would result in a stateful event sender, as it needs to keep a state while waiting for the result event. This makes it harder to create a distributed/decoupled system. **Do we want to push for decoupled CI/CD system solutions?**
- Could there be a reason to send commanding events asynchronously without waiting for their results?
- What happens if you're commanding another service to take a certain action and it fails?
- Would we like the system coordination to take place in each event sender, or should it be handled on a higher level? Is this to be discussed in the CDF Best Practices SIG?

### General Questions
- How does pipeline as code work together with event driven CI/CD?
- Ordering of events, should it be guaranteed?
- Relates also to if events should be linked in some way or not.
- What about idempotency? Should events be idempotent, i.e. should it be possible to send the same event twice?
- What about versioning of the protocol?
- Within the event type (as done in Tekton)?
- Through a version specific linked protocol spec (e.g. through Cloudevents data schema uri)?
- Other alternatives?

### Event relations
- How do you know that an event relates to a previous event?
- Should the connect to each other via context an/or links?
- How can the events be grouped? E.g. A group could consist of all events in a pipeline.
- This could be considered a similar concept to the Git commit 'links', where each commit is linked to its parent commit, using a commit id hash.
- As [Cloudevents could use a uuid](https://github.com/cloudevents/spec/blob/master/spec.md#id) to identify an event, that is also suitable to use in this scenario to get a unique identifier. A hash value could also be considered as an alternative.
- If previous events or other sources should be referenced they need to be persistent, and should not reference any mutable data.
- A reference to an earlier event need not be a URI but could be a simple eventid (e.g. uuid or hash) assuming that there is a consumers storing historical events.
- Trace context - https://www.w3.org/TR/trace-context/

### Apply to industry concepts
- Can we learn/take anything from the OSI model? [OSI model](https://networkel.com/osi-model-7-layer-network-communication/)
- How does the OSI stack (TCP/IP) connect different packages?
- Are there any other concepts that we can use/learn from?

## Event Definitions

This section describes the meaning and usage of each event,
striving to avoid overlap/confusion

### Delivery pipeline events

Delivery pipeline events support large-scale delivery pipelines

#### Component Version Created (draft proposal)

Announces that a new version of a [Baseline Component](https://github.com/erkist/sig-interoperability/tree/erkist-esci/workstreams/events_in_cicd/input/enterprise-scale-ci#baseline-component) (or "Product Component") has been created.

Examples of Component Versions include:
* New version of a software module or application
* New version of a document or piece of configuration
* New revision of a hardware component

The purpose of this event would be for systems to start creating Product Compositions / Baseline Versions that include this Component Version.

Event data:

| Parameter | Description | Comments |
| -------- | -------- | -------- |
| ID | Identifier of component version | Preferrably globally unique, e.g. UUID |
| Version Name | Machine-friendly and human-friendly version tag/number/etc. for component version | e.g "1.4.2-alpha2" |
| Component ID | Identifier of component of which this is a version | The ID by which the component can be retrieved from the source system |
| Component Name | Machine-friendly and human-friendly name of component | e.g. "c37-backbone-router", expected to be used in event filters. <br /><br />Component ID could be used instead if it is human-friendly. |
| Component Display Name | UX/human-friendly display name of component | e.g. "C37 Backbone Router". <br /><br /> Could be fetched from other source when needed |
| Artifacts | List of artifacts part of this component version | Could be a dictionary instead, where the key would indicate what "role" this artifact plays in the component, e.g. `installer: {Artifact123}, calibration: {Artifact456}` |
| Component Track | States what track (e.g. platform variant _(x86_64, ARM etc.)_, project _(e.g. X-DataCenter, X-Cloud etc.)_ or other) the component, of which this is a version, belongs to. | Expected to be used in filters, but could probably be fetched from other source when needed. |

*Note1:* Event can be removed if we say that it is the responsibility of the activity that creates the component version to also create corresponding Product Compositions / Baseline Versions.

*Note2:* Risks partly overlapping with Artifact events, as some component versions represent a single artifact.

#### Composition Defined / Baseline Version Created (draft proposal)

Announces that a new composition of source-files, artifacts, component versions and other compositions/baseline versions, has been created.

*Note:* This event description suffers from a missing piece of terminology to represent the "recipe" by that controls what is included in new compositions. E.g. "The latest stable version (LSV) of this application, the LSV of this library, and the LSV of this configuration file". For now, this will be referred to as a "**Recipe**" until a better name is given. (ESCI calls this a [Baseline](https://github.com/erkist/sig-interoperability/tree/erkist-esci/workstreams/events_in_cicd/input/enterprise-scale-ci#baseline), Eiffel likely has a term for this as well)

| Parameter | Description | Comments |
| -------- | -------- | -------- |
| ID | Identifier of composition | Preferrably globally unique, e.g. UUID |
| Version Name | Machine-friendly and human-friendly version tag/number/etc. for composition | e.g "1.4.2-alpha2" |
| Recipe ID | Identifier of recipe of which this is a composition/version | The ID by which the recipe can be retrieved from the source system |
| Recipe Name | Machine-friendly and human-friendly name of recipe. | e.g. "gemeni-backbone-gen2", expected to be used in event filters. <br /><br />Component ID could be used instead if it is human-friendly. |
| Recipe Display Name | UX/human-friendly display name of recipe | e.g. "Gemeni Backbone, Gen. 2". <br /><br /> Could be fetched from other source when needed |
| *(Eiffel 1/1)* Elements | List of sources, artifacts, components and other compositions part of this composition |
| _or_ |||
| *(ESCI 1/2)* Included Component Versions | List of component versions part of this composition | |
| *(ESCI 2/2)* Included Compositions | List of compositions part of this composition |

#### Confidence Level Modified / Confidence Label Result Changed (draft proposal)

Announces that a Confidence Level / Confidence Label Result (CL/CLR) for a Composition / Baseline Version has been set or updated.

| Parameter | Description | Comments |
| -------- | -------- | -------- |
| ID | Identifier of CL/CLR | Preferrably globally unique, e.g. UUID |
| Value / Result | Value of CL/CLR | Success, failure (+ inconclusive)|
| *(Eiffel 1/4)* Name | Machine-friendly and human-friendly name of confidence level ||
| *(Eiffel 2/4)* Subjects | List of sources, artifacts, components and compositions this confidence level modification applies to ||
| *(Eiffel 3/4)* Sub Confidence Levels | List of other confidence level modifications that resulted in this confidence level modification | Used for "summarizing" (e.g. "parent") confidence levels|
| *(Eiffel 4/4)* Causes | List of e.g. activities or test suites that lead to this confidence level modification ||
| _or_ |||
| *(ESCI 1/3)* Confidence Label ID | ID of confidence label for which this is a result | The ID by which more information can be fetched from other source when needed |
| *(ESCI 2/3)* Confidence Label Name | Machine-friendly and human-friendly confidence label for which this is a result ||
| *(ESCI 3/3)* Result Links | List of links to results that contributed to this confidence label result ||

#### Resource Set Allocated

*Note:* The allocation and deallocation events could be merged into a "status changed" event, which could also include resource sets being brought offline or online.

TBW

#### Resource Set Deallocated

TBW

#### Test Execution Recipe Collection Created

TBW

#### Activity Block Run Created

TBW

#### Activity Block Run Started

TBW

#### Activity Block Run Finished

TBW