From be08fc660216d92b5b8bb14d9d1d9a6c3430b247 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Fri, 18 Nov 2022 15:17:43 +0000 Subject: [PATCH 01/10] Add Incident events Introduce incident events. Partially-fixes: #59 Signed-off-by: Andrea Frittoli --- README.md | 8 +- ...line-events.md => continuous-deployment.md | 0 ...ine-events.md => continuous-integration.md | 0 continuous-operations.md | 73 +++++++++++++++++++ spec.md | 8 +- tools/event-version.sh | 2 +- 6 files changed, 86 insertions(+), 5 deletions(-) rename continuous-deployment-pipeline-events.md => continuous-deployment.md (100%) rename continuous-integration-pipeline-events.md => continuous-integration.md (100%) create mode 100644 continuous-operations.md diff --git a/README.md b/README.md index 333a13a5..3ceaa94f 100644 --- a/README.md +++ b/README.md @@ -70,11 +70,15 @@ Definition of specific events that are fundamental to pipeline execution and orc Handling Events relating to changes in version management of Source Code and related assets -### [Continuous Integration Events](./continuous-integration-pipeline-events.md) +### [Continuous Integration Events](./continuous-integration.md) Handling Events associated with Continuous Integration activities, typically involving build and test -### [Continuous Deployment Events](./continuous-deployment-pipeline-events.md) +### [Continuous Deployment Events](./continuous-deployment.md) + +Handling Events associated with Continuous Deployment activities + +### [Continuous Operatorations](./continuous-operations.md) Handling Events associated with Continuous Deployment activities diff --git a/continuous-deployment-pipeline-events.md b/continuous-deployment.md similarity index 100% rename from continuous-deployment-pipeline-events.md rename to continuous-deployment.md diff --git a/continuous-integration-pipeline-events.md b/continuous-integration.md similarity index 100% rename from continuous-integration-pipeline-events.md rename to continuous-integration.md diff --git a/continuous-operations.md b/continuous-operations.md new file mode 100644 index 00000000..0adb132e --- /dev/null +++ b/continuous-operations.md @@ -0,0 +1,73 @@ + +# Continuous Operations Events + +Continuous Operations events are related to the operation of services deployed in target environments, tracking of incidents and their remediation. Incidents, and their resolution, can be detected by a number of different actors, like the end-user, a quality gate, a monitoring system, an SRE through a ticketing system or event the service itself. +Multiple events may be associated to the same incident as well as its resolution, coming from diverse sources. + +## Subjects + +This specification defines one subject in this stage, the [`incident`](#incident). To quote the definition of the term from the NIST glossary, and [incident][] is: + +> An occurrence that actually or potentially jeopardizes the confidentiality, integrity, or availability of an information system or the information the system processes, stores, or transmits or that constitutes a violation or imminent threat of violation of security policies, security procedures, or acceptable use policies. + +| Subject | Description | Predicates | +|---------|-------------|------------| +| [`incident`](#incident) | A problem in a production environment | [`reported`](#incident-reported), [`resolved`](#incident-resolved)| + +### `incident` + +An `incident` represents a problem in a production environment. + +| Field | Type | Description | Examples | +|-------|------|-------------|----------| +| id | `String` | Uniquely identifies the subject within the source. | `04896C75-F34D-40FF-A584-3F2B71CB9D47`, `issue123`, `risk-CVE123` | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `region1/production`, `monitoring-system/metricA`| +| description | `String` | Short, free style description of the incident | "Response time above 10ms", "New CVE-123 detected" | +| environment | `Object` ([`environment`](./continuous-deployment.md#environment)) | Reference to the environment | `{"id": "production"}`, `{"id": "staging"}`, `{"id": "prod123", "source": "iaas-region-1"}` | +| service | `Object` ([`service`](./continuous-deployment.md#service)) | Reference to the service | `{"id": "service123"}`, `{"id": "service123", "source": "region1/k8s/namespace"}` | +| artifactId | `Purl` | Identifier of the artifact deployed with this service | `0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `927aa808433d17e315a258b98e2f1a55f8258e0cb782ccb76280646d0dbe17b5`, `six-1.14.0-py2.py3-none-any.whl` | + +## Events + +### `incident reported` + +This event represents an incident that has been detected by a system or human. + +- Event Type: __`dev.cdevents.incident.reported.0.1.0-draft`__ +- Predicate: reported +- Subject: [`incident`](#incident) + +| Field | Type | Description | Examples | Mandatory ✅ | +|-------|------|-------------|----------|----------------------------| +| id | `String` | Uniquely identifies the subject within the source. | `04896C75-F34D-40FF-A584-3F2B71CB9D47`, `issue123`, `risk-CVE123` | ✅ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `region1/production`, `monitoring-system/metricA`| | +| description | `String` | Short, free style description of the incident | "Response time above 10ms", "New CVE-123 detected" | | +| environment | `Object` ([`environment`](./continuous-deployment.md#environment)) | Reference to the environment | `{"id": "production"}`, `{"id": "staging"}`, `{"id": "prod123", "source": "iaas-region-1"}` | ✅ | +| service | `Object` ([`service`](./continuous-deployment.md#service)) | Reference to the service | `{"id": "service123"}`, `{"id": "service123", "source": "region1/k8s/namespace"}` | | +| artifactId | `Purl` | Identifier of the artifact deployed with this service | `0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `927aa808433d17e315a258b98e2f1a55f8258e0cb782ccb76280646d0dbe17b5`, `six-1.14.0-py2.py3-none-any.whl` | | + +### `incident resolved` + +This event represents an environment that has been modified. + +- Event Type: __`dev.cdevents.incident.resolved.0.1.0-draft`__ +- Predicate: resolved +- Subject: [`incident`](#incident) + +| Field | Type | Description | Examples | Mandatory ✅ | +|-------|------|-------------|----------|----------------------------| +| id | `String` | Uniquely identifies the subject within the source. | `04896C75-F34D-40FF-A584-3F2B71CB9D47`, `issue123`, `risk-CVE123` | ✅ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `region1/production`, `monitoring-system/metricA`| | +| description | `String` | Short, free style description of the incident resolution | "Response time restored below 10ms", "CVE-123 acknowledged as non-exploitable" | | +| environment | `Object` ([`environment`](./continuous-deployment.md#environment)) | Reference to the environment | `{"id": "production"}`, `{"id": "staging"}`, `{"id": "prod123", "source": "iaas-region-1"}` | ✅ | +| service | `Object` ([`service`](./continuous-deployment.md#service)) | Reference to the service | `{"id": "service123"}`, `{"id": "service123", "source": "region1/k8s/namespace"}` | | +| artifactId | `Purl` | Identifier of the artifact deployed with this service | `0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `927aa808433d17e315a258b98e2f1a55f8258e0cb782ccb76280646d0dbe17b5`, `six-1.14.0-py2.py3-none-any.whl` | | + +[incident]: https://csrc.nist.gov/glossary/term/incident \ No newline at end of file diff --git a/spec.md b/spec.md index 7df5c3ff..30e32c27 100644 --- a/spec.md +++ b/spec.md @@ -491,14 +491,18 @@ dedicated document in the spec: - __[Source Code Version Control](source-code-version-control.md)__: Events emitted by changes in source code or by the creation, modification or deletion of new repositories that hold source code. -- __[Continuous Integration](continuous-integration-pipeline-events.md)__: +- __[Continuous Integration](continuous-integration.md)__: includes events related to building, testings, packaging and releasing software artifacts, usually binaries. -- __[Continuous Deployment](continuous-deployment-pipeline-events.md)__: +- __[Continuous Deployment](continuous-deployment.md)__: include events related with environments where the artifacts produced by the integration pipelines actually run. These are usually services running in a specific environment (dev, QA, production), or embedded software running in a specific hardware. +- __[Continuous Operations](continuous-operations.md)__: include events related + to the health of the services deployed and running in a specific environment. + Health may refer to different aspects such as performance, availability, + response time and more. The grouping may serve in future as a reference for different CDEvents compliance profiles, which can be supported individually by implementing diff --git a/tools/event-version.sh b/tools/event-version.sh index 15bfa7a0..ab435184 100755 --- a/tools/event-version.sh +++ b/tools/event-version.sh @@ -158,7 +158,7 @@ VERSION="${MAJOR_VERSION}.${MINOR_VERSION}.${PATCH_VERSION}${DRAFT_VERSION}" sed -i ".backup" -e 's,"dev.cdevents.*","dev.cdevents.'${SUBJECT}'.'${PREDICATE}'.'${VERSION}'",g' "${SCHEMA_FILE}" # Update examples in docs -for doc in core source-code-version-control continuous-integration-pipeline-events continuous-deployment-pipeline-events; do +for doc in core source-code-version-control continuous-integration continuous-deployment; do sed -i ".backup" -e 's,__`dev.cdevents.'${SUBJECT}'.'${PREDICATE}'.*`__,__`dev.cdevents.'${SUBJECT}'.'${PREDICATE}'.'${VERSION}'`__,g' "${doc}.md" done From 49f4ca2539d9ef154fb848ad60845c2b715098d4 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Mon, 30 Jan 2023 10:33:01 +0000 Subject: [PATCH 02/10] Change predicate from reported to detected Signed-off-by: Andrea Frittoli --- continuous-operations.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/continuous-operations.md b/continuous-operations.md index 0adb132e..c33b566c 100644 --- a/continuous-operations.md +++ b/continuous-operations.md @@ -19,7 +19,7 @@ This specification defines one subject in this stage, the [`incident`](#incident | Subject | Description | Predicates | |---------|-------------|------------| -| [`incident`](#incident) | A problem in a production environment | [`reported`](#incident-reported), [`resolved`](#incident-resolved)| +| [`incident`](#incident) | A problem in a production environment | [`detected`](#incident-detected), [`resolved`](#incident-resolved)| ### `incident` @@ -36,12 +36,12 @@ An `incident` represents a problem in a production environment. ## Events -### `incident reported` +### `incident detected` This event represents an incident that has been detected by a system or human. -- Event Type: __`dev.cdevents.incident.reported.0.1.0-draft`__ -- Predicate: reported +- Event Type: __`dev.cdevents.incident.detected.0.1.0-draft`__ +- Predicate: detected - Subject: [`incident`](#incident) | Field | Type | Description | Examples | Mandatory ✅ | From 84e8a0ac2dccaf42aeba6eea111ea5b2fbe1eaa4 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Mon, 30 Jan 2023 10:42:20 +0000 Subject: [PATCH 03/10] Add schema files Signed-off-by: Andrea Frittoli --- schemas/incidentdetected.json | 129 ++++++++++++++++++++++++++++++++++ schemas/incidentresolved.json | 129 ++++++++++++++++++++++++++++++++++ 2 files changed, 258 insertions(+) create mode 100644 schemas/incidentdetected.json create mode 100644 schemas/incidentresolved.json diff --git a/schemas/incidentdetected.json b/schemas/incidentdetected.json new file mode 100644 index 00000000..ea5623db --- /dev/null +++ b/schemas/incidentdetected.json @@ -0,0 +1,129 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.2.0-draft/schema/incident-detected-event", + "properties": { + "context": { + "properties": { + "version": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1 + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.incident.detected.0.1.0-draft" + ], + "default": "dev.cdevents.incident.detected.0.1.0-draft" + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "version", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + }, + "type": { + "type": "string", + "minLength": 1 + }, + "content": { + "properties": { + "description": { + "type": "string" + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "service": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "artifactId": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "type", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} \ No newline at end of file diff --git a/schemas/incidentresolved.json b/schemas/incidentresolved.json new file mode 100644 index 00000000..f9f91651 --- /dev/null +++ b/schemas/incidentresolved.json @@ -0,0 +1,129 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.2.0-draft/schema/incident-resolved-event", + "properties": { + "context": { + "properties": { + "version": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1 + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.incident.resolved.0.1.0-draft" + ], + "default": "dev.cdevents.incident.resolved.0.1.0-draft" + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "version", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + }, + "type": { + "type": "string", + "minLength": 1 + }, + "content": { + "properties": { + "description": { + "type": "string" + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "service": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "artifactId": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "type", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} \ No newline at end of file From b86dac37f9bce31e8161e0378dd4df6213121c97 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Mon, 30 Jan 2023 10:51:37 +0000 Subject: [PATCH 04/10] Fix continuous operations description in README Signed-off-by: Andrea Frittoli --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3ceaa94f..3439ad41 100644 --- a/README.md +++ b/README.md @@ -78,9 +78,9 @@ Handling Events associated with Continuous Integration activities, typically inv Handling Events associated with Continuous Deployment activities -### [Continuous Operatorations](./continuous-operations.md) +### [Continuous Operations](./continuous-operations.md) -Handling Events associated with Continuous Deployment activities +Handling Events associated with the health of the services deployed and running in a specific environment ### [CloudEvents Binding and Transport](./cloudevents-binding.md) From 07514d746e72b59d1f5ca5adbbe99fd7af1b5b5a Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Tue, 31 Jan 2023 13:41:33 +0000 Subject: [PATCH 05/10] Add incident reported event Signed-off-by: Andrea Frittoli --- continuous-operations.md | 20 ++++- schemas/incidentdetected.json | 5 +- schemas/incidentreported.json | 138 ++++++++++++++++++++++++++++++++++ schemas/incidentresolved.json | 5 +- 4 files changed, 165 insertions(+), 3 deletions(-) create mode 100644 schemas/incidentreported.json diff --git a/continuous-operations.md b/continuous-operations.md index c33b566c..5c433308 100644 --- a/continuous-operations.md +++ b/continuous-operations.md @@ -19,7 +19,7 @@ This specification defines one subject in this stage, the [`incident`](#incident | Subject | Description | Predicates | |---------|-------------|------------| -| [`incident`](#incident) | A problem in a production environment | [`detected`](#incident-detected), [`resolved`](#incident-resolved)| +| [`incident`](#incident) | A problem in a production environment | [`detected`](#incident-detected), [`reported`](#incident-reported), [`resolved`](#incident-resolved)| ### `incident` @@ -53,6 +53,24 @@ This event represents an incident that has been detected by a system or human. | service | `Object` ([`service`](./continuous-deployment.md#service)) | Reference to the service | `{"id": "service123"}`, `{"id": "service123", "source": "region1/k8s/namespace"}` | | | artifactId | `Purl` | Identifier of the artifact deployed with this service | `0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `927aa808433d17e315a258b98e2f1a55f8258e0cb782ccb76280646d0dbe17b5`, `six-1.14.0-py2.py3-none-any.whl` | | +### `incident reported` + +This event represents an incident that has been reported through a ticketing system. Compared to the `detected` predicated, it introduces a ticket URI. + +- Event Type: __`dev.cdevents.incident.reported.0.1.0-draft`__ +- Predicate: reported +- Subject: [`incident`](#incident) + +| Field | Type | Description | Examples | Mandatory ✅ | +|-------|------|-------------|----------|----------------------------| +| id | `String` | Uniquely identifies the subject within the source. | `04896C75-F34D-40FF-A584-3F2B71CB9D47`, `issue123`, `risk-CVE123` | ✅ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `region1/production`, `monitoring-system/metricA`| | +| description | `String` | Short, free style description of the incident | "Response time above 10ms", "New CVE-123 detected" | | +| environment | `Object` ([`environment`](./continuous-deployment.md#environment)) | Reference to the environment | `{"id": "production"}`, `{"id": "staging"}`, `{"id": "prod123", "source": "iaas-region-1"}` | ✅ | +| tickerURI | `URI` | URI of the ticket | `example.issues.com/ticket123` | ✅ | +| service | `Object` ([`service`](./continuous-deployment.md#service)) | Reference to the service | `{"id": "service123"}`, `{"id": "service123", "source": "region1/k8s/namespace"}` | | +| artifactId | `Purl` | Identifier of the artifact deployed with this service | `0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `927aa808433d17e315a258b98e2f1a55f8258e0cb782ccb76280646d0dbe17b5`, `six-1.14.0-py2.py3-none-any.whl` | | + ### `incident resolved` This event represents an environment that has been modified. diff --git a/schemas/incidentdetected.json b/schemas/incidentdetected.json index ea5623db..14e6cf59 100644 --- a/schemas/incidentdetected.json +++ b/schemas/incidentdetected.json @@ -94,7 +94,10 @@ } }, "additionalProperties": false, - "type": "object" + "type": "object", + "required": [ + "environment" + ] } }, "additionalProperties": false, diff --git a/schemas/incidentreported.json b/schemas/incidentreported.json new file mode 100644 index 00000000..4f5f4114 --- /dev/null +++ b/schemas/incidentreported.json @@ -0,0 +1,138 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.2.0-draft/schema/incident-detected-event", + "properties": { + "context": { + "properties": { + "version": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1 + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.incident.detected.0.1.0-draft" + ], + "default": "dev.cdevents.incident.detected.0.1.0-draft" + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "version", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + }, + "type": { + "type": "string", + "minLength": 1 + }, + "content": { + "properties": { + "description": { + "type": "string" + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "ticketURI": { + "type": "string", + "format": "uri", + "minLength": 1 + }, + "service": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "artifactId": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "environment", + "tickerURI" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "type", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} \ No newline at end of file diff --git a/schemas/incidentresolved.json b/schemas/incidentresolved.json index f9f91651..6505b1a8 100644 --- a/schemas/incidentresolved.json +++ b/schemas/incidentresolved.json @@ -94,7 +94,10 @@ } }, "additionalProperties": false, - "type": "object" + "type": "object", + "required": [ + "environment" + ] } }, "additionalProperties": false, From cf9ed979f93fa32f31a029bb53bad7deaa8c99c6 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Thu, 2 Feb 2023 13:22:55 +0000 Subject: [PATCH 06/10] Update schema, add examples Signed-off-by: Andrea Frittoli --- examples/incidentdetected.json | 32 ++++++++++++++++++++++++++++++++ examples/incidentreported.json | 33 +++++++++++++++++++++++++++++++++ examples/incidentresolved.json | 32 ++++++++++++++++++++++++++++++++ schemas/incidentdetected.json | 17 ++++++++++++----- schemas/incidentreported.json | 17 ++++++++++++----- schemas/incidentresolved.json | 17 ++++++++++++----- 6 files changed, 133 insertions(+), 15 deletions(-) create mode 100644 examples/incidentdetected.json create mode 100644 examples/incidentreported.json create mode 100644 examples/incidentresolved.json diff --git a/examples/incidentdetected.json b/examples/incidentdetected.json new file mode 100644 index 00000000..c49f4e34 --- /dev/null +++ b/examples/incidentdetected.json @@ -0,0 +1,32 @@ +{ + "context": { + "version": "0.2.0-draft", + "id": "F4BD2B55-B6F6-4F44-AF72-BD2D0E7A8708", + "source": "/monitoring/prod1", + "type": "dev.cdevents.incident.detected.0.1.0-draft", + "timestamp": "2022-11-11T13:52:20.079Z" + }, + "subject": { + "id": "incident-123", + "source": "/monitoring/prod1", + "type": "incident", + "content": { + "description": "Response time above threshold of 100ms", + "environment": { + "id": "prod1", + "source": "/iaas/geo1" + }, + "service": { + "id": "myApp", + "source": "/clusterA/namespaceB" + }, + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427" + } + }, + "customData": { + "metric": "responseTime", + "threshold": "100ms", + "value": "200ms" + }, + "customDataContentType": "application/json" +} diff --git a/examples/incidentreported.json b/examples/incidentreported.json new file mode 100644 index 00000000..ea994930 --- /dev/null +++ b/examples/incidentreported.json @@ -0,0 +1,33 @@ +{ + "context": { + "version": "0.2.0-draft", + "id": "F4BD2B55-B6F6-4F44-AF72-BD2D0E7A8708", + "source": "/monitoring/prod1", + "type": "dev.cdevents.incident.reported.0.1.0-draft", + "timestamp": "2022-11-11T13:52:20.079Z" + }, + "subject": { + "id": "incident-123", + "source": "/monitoring/prod1", + "type": "incident", + "content": { + "description": "Response time above threshold of 100ms", + "environment": { + "id": "prod1", + "source": "/iaas/geo1" + }, + "service": { + "id": "myApp", + "source": "/clusterA/namespaceB" + }, + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", + "ticketURI": "https://my-issues.example/incidents/ticket-345" + } + }, + "customData": { + "severity": "medium", + "priority": "critical", + "reportedBy": "userId" + }, + "customDataContentType": "application/json" +} diff --git a/examples/incidentresolved.json b/examples/incidentresolved.json new file mode 100644 index 00000000..c15ce6df --- /dev/null +++ b/examples/incidentresolved.json @@ -0,0 +1,32 @@ +{ + "context": { + "version": "0.2.0-draft", + "id": "F4BD2B55-B6F6-4F44-AF72-BD2D0E7A8708", + "source": "/monitoring/prod1", + "type": "dev.cdevents.incident.resolved.0.1.0-draft", + "timestamp": "2022-11-11T13:52:20.079Z" + }, + "subject": { + "id": "incident-123", + "source": "/monitoring/prod1", + "type": "incident", + "content": { + "description": "Response time restored below 100ms", + "environment": { + "id": "prod1", + "source": "/iaas/geo1" + }, + "service": { + "id": "myApp", + "source": "/clusterA/namespaceB" + }, + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93439" + } + }, + "customData": { + "metric": "responseTime", + "threshold": "100ms", + "value": "70ms" + }, + "customDataContentType": "application/json" +} diff --git a/schemas/incidentdetected.json b/schemas/incidentdetected.json index 14e6cf59..dae5e5f8 100644 --- a/schemas/incidentdetected.json +++ b/schemas/incidentdetected.json @@ -14,7 +14,8 @@ }, "source": { "type": "string", - "minLength": 1 + "minLength": 1, + "format": "uri-reference" }, "type": { "type": "string", @@ -45,11 +46,15 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" }, "type": { "type": "string", - "minLength": 1 + "enum": [ + "incident" + ], + "default": "incident" }, "content": { "properties": { @@ -63,7 +68,8 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" } }, "additionalProperties": false, @@ -79,7 +85,8 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" } }, "additionalProperties": false, diff --git a/schemas/incidentreported.json b/schemas/incidentreported.json index 4f5f4114..61d8004a 100644 --- a/schemas/incidentreported.json +++ b/schemas/incidentreported.json @@ -14,7 +14,8 @@ }, "source": { "type": "string", - "minLength": 1 + "minLength": 1, + "format": "uri-reference" }, "type": { "type": "string", @@ -45,11 +46,15 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" }, "type": { "type": "string", - "minLength": 1 + "enum": [ + "incident" + ], + "default": "incident" }, "content": { "properties": { @@ -63,7 +68,8 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" } }, "additionalProperties": false, @@ -84,7 +90,8 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" } }, "additionalProperties": false, diff --git a/schemas/incidentresolved.json b/schemas/incidentresolved.json index 6505b1a8..356d3fef 100644 --- a/schemas/incidentresolved.json +++ b/schemas/incidentresolved.json @@ -14,7 +14,8 @@ }, "source": { "type": "string", - "minLength": 1 + "minLength": 1, + "format": "uri-reference" }, "type": { "type": "string", @@ -45,11 +46,15 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" }, "type": { "type": "string", - "minLength": 1 + "enum": [ + "incident" + ], + "default": "incident" }, "content": { "properties": { @@ -63,7 +68,8 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" } }, "additionalProperties": false, @@ -79,7 +85,8 @@ "minLength": 1 }, "source": { - "type": "string" + "type": "string", + "format": "uri-reference" } }, "additionalProperties": false, From 354560bdf563aad7dae131434813c140e1bc6ef5 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Thu, 2 Feb 2023 13:44:44 +0000 Subject: [PATCH 07/10] Address review comments Signed-off-by: Andrea Frittoli --- README.md | 2 +- continuous-operations.md | 6 +++--- schemas/incidentreported.json | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3439ad41..529da3f6 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ Handling Events associated with Continuous Integration activities, typically inv Handling Events associated with Continuous Deployment activities -### [Continuous Operations](./continuous-operations.md) +### [Continuous Operations Events](./continuous-operations.md) Handling Events associated with the health of the services deployed and running in a specific environment diff --git a/continuous-operations.md b/continuous-operations.md index 5c433308..56cc5bad 100644 --- a/continuous-operations.md +++ b/continuous-operations.md @@ -8,7 +8,7 @@ description: > --> # Continuous Operations Events -Continuous Operations events are related to the operation of services deployed in target environments, tracking of incidents and their remediation. Incidents, and their resolution, can be detected by a number of different actors, like the end-user, a quality gate, a monitoring system, an SRE through a ticketing system or event the service itself. +Continuous Operations events are related to the operation of services deployed in target environments, tracking of incidents and their resolution. Incidents, and their resolution, can be detected by a number of different actors, like the end-user, a quality gate, a monitoring system, an SRE through a ticketing system or even the service itself. Multiple events may be associated to the same incident as well as its resolution, coming from diverse sources. ## Subjects @@ -67,13 +67,13 @@ This event represents an incident that has been reported through a ticketing sys | source | `URI-Reference` | [source](../spec.md#source) from the context | `region1/production`, `monitoring-system/metricA`| | | description | `String` | Short, free style description of the incident | "Response time above 10ms", "New CVE-123 detected" | | | environment | `Object` ([`environment`](./continuous-deployment.md#environment)) | Reference to the environment | `{"id": "production"}`, `{"id": "staging"}`, `{"id": "prod123", "source": "iaas-region-1"}` | ✅ | -| tickerURI | `URI` | URI of the ticket | `example.issues.com/ticket123` | ✅ | +| ticketURI | `URI` | URI of the ticket | `example.issues.com/ticket123` | ✅ | | service | `Object` ([`service`](./continuous-deployment.md#service)) | Reference to the service | `{"id": "service123"}`, `{"id": "service123", "source": "region1/k8s/namespace"}` | | | artifactId | `Purl` | Identifier of the artifact deployed with this service | `0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `927aa808433d17e315a258b98e2f1a55f8258e0cb782ccb76280646d0dbe17b5`, `six-1.14.0-py2.py3-none-any.whl` | | ### `incident resolved` -This event represents an environment that has been modified. +This event represents an incident that has been resolved, meaning that the situation identified by the incident has been addressed or that it ceased to happen or that it has been acknowledged. - Event Type: __`dev.cdevents.incident.resolved.0.1.0-draft`__ - Predicate: resolved diff --git a/schemas/incidentreported.json b/schemas/incidentreported.json index 61d8004a..70cb7e9d 100644 --- a/schemas/incidentreported.json +++ b/schemas/incidentreported.json @@ -109,7 +109,7 @@ "type": "object", "required": [ "environment", - "tickerURI" + "ticketURI" ] } }, From 8a9905432d3637bf07b96609856f9d6dc764fbf6 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Sun, 12 Feb 2023 21:07:18 +0000 Subject: [PATCH 08/10] Address review comments Signed-off-by: Andrea Frittoli --- continuous-operations.md | 3 +-- schemas/incidentreported.json | 6 +++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/continuous-operations.md b/continuous-operations.md index 56cc5bad..f03205f9 100644 --- a/continuous-operations.md +++ b/continuous-operations.md @@ -9,7 +9,6 @@ description: > # Continuous Operations Events Continuous Operations events are related to the operation of services deployed in target environments, tracking of incidents and their resolution. Incidents, and their resolution, can be detected by a number of different actors, like the end-user, a quality gate, a monitoring system, an SRE through a ticketing system or even the service itself. -Multiple events may be associated to the same incident as well as its resolution, coming from diverse sources. ## Subjects @@ -73,7 +72,7 @@ This event represents an incident that has been reported through a ticketing sys ### `incident resolved` -This event represents an incident that has been resolved, meaning that the situation identified by the incident has been addressed or that it ceased to happen or that it has been acknowledged. +This event represents an incident that has been resolved, meaning that the problem identified by the incident has been solved or recalled. - Event Type: __`dev.cdevents.incident.resolved.0.1.0-draft`__ - Predicate: resolved diff --git a/schemas/incidentreported.json b/schemas/incidentreported.json index 70cb7e9d..049212d5 100644 --- a/schemas/incidentreported.json +++ b/schemas/incidentreported.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://cdevents.dev/0.2.0-draft/schema/incident-detected-event", + "$id": "https://cdevents.dev/0.2.0-draft/schema/incident-reported-event", "properties": { "context": { "properties": { @@ -20,9 +20,9 @@ "type": { "type": "string", "enum": [ - "dev.cdevents.incident.detected.0.1.0-draft" + "dev.cdevents.incident.reported.0.1.0-draft" ], - "default": "dev.cdevents.incident.detected.0.1.0-draft" + "default": "dev.cdevents.incident.reported.0.1.0-draft" }, "timestamp": { "type": "string", From 91b9443ad40eab8e656ecc987669161b0dd4eb04 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Fri, 3 Mar 2023 22:45:05 +0000 Subject: [PATCH 09/10] Remove uri-reference formats and type enum Signed-off-by: Andrea Frittoli --- schemas/incidentdetected.json | 18 +++++------------- schemas/incidentreported.json | 18 +++++------------- schemas/incidentresolved.json | 18 +++++------------- 3 files changed, 15 insertions(+), 39 deletions(-) diff --git a/schemas/incidentdetected.json b/schemas/incidentdetected.json index dae5e5f8..b178d945 100644 --- a/schemas/incidentdetected.json +++ b/schemas/incidentdetected.json @@ -14,8 +14,7 @@ }, "source": { "type": "string", - "minLength": 1, - "format": "uri-reference" + "minLength": 1 }, "type": { "type": "string", @@ -46,15 +45,10 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" }, "type": { - "type": "string", - "enum": [ - "incident" - ], - "default": "incident" + "type": "string" }, "content": { "properties": { @@ -68,8 +62,7 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" } }, "additionalProperties": false, @@ -85,8 +78,7 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" } }, "additionalProperties": false, diff --git a/schemas/incidentreported.json b/schemas/incidentreported.json index 049212d5..a73fcf7b 100644 --- a/schemas/incidentreported.json +++ b/schemas/incidentreported.json @@ -14,8 +14,7 @@ }, "source": { "type": "string", - "minLength": 1, - "format": "uri-reference" + "minLength": 1 }, "type": { "type": "string", @@ -46,15 +45,10 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" }, "type": { - "type": "string", - "enum": [ - "incident" - ], - "default": "incident" + "type": "string" }, "content": { "properties": { @@ -68,8 +62,7 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" } }, "additionalProperties": false, @@ -90,8 +83,7 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" } }, "additionalProperties": false, diff --git a/schemas/incidentresolved.json b/schemas/incidentresolved.json index 356d3fef..c7f89ba1 100644 --- a/schemas/incidentresolved.json +++ b/schemas/incidentresolved.json @@ -14,8 +14,7 @@ }, "source": { "type": "string", - "minLength": 1, - "format": "uri-reference" + "minLength": 1 }, "type": { "type": "string", @@ -46,15 +45,10 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" }, "type": { - "type": "string", - "enum": [ - "incident" - ], - "default": "incident" + "type": "string" }, "content": { "properties": { @@ -68,8 +62,7 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" } }, "additionalProperties": false, @@ -85,8 +78,7 @@ "minLength": 1 }, "source": { - "type": "string", - "format": "uri-reference" + "type": "string" } }, "additionalProperties": false, From 2601c313f6005d888c287fbbdcb4b2fa839a7344 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Fri, 3 Mar 2023 23:29:14 +0000 Subject: [PATCH 10/10] Fix the versions script with the new group Signed-off-by: Andrea Frittoli --- tools/event-version.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/event-version.sh b/tools/event-version.sh index ab435184..dc21033f 100755 --- a/tools/event-version.sh +++ b/tools/event-version.sh @@ -158,7 +158,7 @@ VERSION="${MAJOR_VERSION}.${MINOR_VERSION}.${PATCH_VERSION}${DRAFT_VERSION}" sed -i ".backup" -e 's,"dev.cdevents.*","dev.cdevents.'${SUBJECT}'.'${PREDICATE}'.'${VERSION}'",g' "${SCHEMA_FILE}" # Update examples in docs -for doc in core source-code-version-control continuous-integration continuous-deployment; do +for doc in core source-code-version-control continuous-integration continuous-deployment continuous-operations; do sed -i ".backup" -e 's,__`dev.cdevents.'${SUBJECT}'.'${PREDICATE}'.*`__,__`dev.cdevents.'${SUBJECT}'.'${PREDICATE}'.'${VERSION}'`__,g' "${doc}.md" done