From 036cd64634963097a9088a72f7840a6b4d004515 Mon Sep 17 00:00:00 2001 From: xibz Date: Tue, 21 Jul 2026 11:35:31 -0500 Subject: [PATCH 1/4] feat(deployment): add deployment subject and queued/started/finished events Deployments today are only visible as a side effect of a service state change (service.deployed/service.upgraded), with no way to observe the orchestration act itself: when a rollout started, when it finished, or how long it took. This adds deployment as its own subject with the standard queued/started/finished lifecycle, giving DORA-style tooling an explicit deployment-duration/outcome fact independent of the resulting service entity. service.deployed/service.upgraded are unchanged; whether to deprecate them is a separate decision left for a follow-up once deployment.* has implementation experience. The original proposal also included a targetRollout subject to model fan-out to multiple destinations within one deployment; that's split into a separate follow-up PR pending more implementation experience. Signed-off-by: xibz --- conformance/deployment_finished.json | 22 +++++ conformance/deployment_queued.json | 21 ++++ conformance/deployment_started.json | 21 ++++ continuous-deployment.md | 60 +++++++++++- schemas/_defs/deployment.json | 16 +++ schemas/_defs/finished.json | 20 ++++ schemas/_defs/queued.json | 18 ++++ schemas/deploymentfinished.json | 140 +++++++++++++++++++++++++++ schemas/deploymentqueued.json | 130 +++++++++++++++++++++++++ schemas/deploymentstarted.json | 130 +++++++++++++++++++++++++ 10 files changed, 577 insertions(+), 1 deletion(-) create mode 100644 conformance/deployment_finished.json create mode 100644 conformance/deployment_queued.json create mode 100644 conformance/deployment_started.json create mode 100644 schemas/_defs/deployment.json create mode 100644 schemas/_defs/finished.json create mode 100644 schemas/_defs/queued.json create mode 100644 schemas/deploymentfinished.json create mode 100644 schemas/deploymentqueued.json create mode 100644 schemas/deploymentstarted.json diff --git a/conformance/deployment_finished.json b/conformance/deployment_finished.json new file mode 100644 index 0000000..d27f5c9 --- /dev/null +++ b/conformance/deployment_finished.json @@ -0,0 +1,22 @@ +{ + "context": { + "specversion": "0.6.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", + "source": "/event/source/123", + "type": "dev.cdevents.deployment.finished.0.1.0", + "timestamp": "2023-03-20T14:27:05.315384Z", + "schemaUri": "https://myorg.com/schema/custom" + }, + "subject": { + "id": "mySubject123", + "source": "/event/source/123", + "content": { + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", + "environment": { + "id": "test123" + }, + "outcome": "success" + } + } +} diff --git a/conformance/deployment_queued.json b/conformance/deployment_queued.json new file mode 100644 index 0000000..1dd4656 --- /dev/null +++ b/conformance/deployment_queued.json @@ -0,0 +1,21 @@ +{ + "context": { + "specversion": "0.6.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", + "source": "/event/source/123", + "type": "dev.cdevents.deployment.queued.0.1.0", + "timestamp": "2023-03-20T14:27:05.315384Z", + "schemaUri": "https://myorg.com/schema/custom" + }, + "subject": { + "id": "mySubject123", + "source": "/event/source/123", + "content": { + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", + "environment": { + "id": "test123" + } + } + } +} diff --git a/conformance/deployment_started.json b/conformance/deployment_started.json new file mode 100644 index 0000000..0985fec --- /dev/null +++ b/conformance/deployment_started.json @@ -0,0 +1,21 @@ +{ + "context": { + "specversion": "0.6.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", + "source": "/event/source/123", + "type": "dev.cdevents.deployment.started.0.1.0", + "timestamp": "2023-03-20T14:27:05.315384Z", + "schemaUri": "https://myorg.com/schema/custom" + }, + "subject": { + "id": "mySubject123", + "source": "/event/source/123", + "content": { + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", + "environment": { + "id": "test123" + } + } + } +} diff --git a/continuous-deployment.md b/continuous-deployment.md index fba55e9..10a73d9 100644 --- a/continuous-deployment.md +++ b/continuous-deployment.md @@ -14,12 +14,13 @@ Continuous Deployment (CD) events are related to continuous deployment pipelines ## Subjects -This specification defines two subjects in this stage: `environment` and `service`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. +This specification defines three subjects in this stage: `environment`, `service`, and `deployment`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the act of applying a version of a release unit to an environment. | Subject | Description | Predicates | |---------|-------------|------------| | [`environment`](#environment) | An environment where to run services | [`created`](#environment-created), [`modified`](#environment-modified), [`deleted`](#environment-deleted)| | [`service`](#service) | A service | [`deployed`](#service-deployed), [`upgraded`](#service-upgraded), [`rolledback`](#service-rolledback), [`removed`](#service-removed), [`published`](#service-published)| +| [`deployment`](#deployment) | The act of deploying a release unit to an environment | [`queued`](#deployment-queued), [`started`](#deployment-started), [`finished`](#deployment-finished)| ### `environment` @@ -43,6 +44,17 @@ A `service` can represent for example a binary that is running, a daemon, an app | environment | `Object` ([`environment`](#environment)) | Reference for the environment where the service runs | `{"id": "1234"}`, `{"id": "maven123, "source": "tekton-dev-123"}` | | artifactId | `Purl` | Identifier of the artifact deployed with this service | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | +### `deployment` + +A `deployment` is the act of applying a version of a release unit to an environment. A deployment is a canonical SDLC fact: it represents the change to the running system that resulted from a release, as distinct in meaning from the orchestration that performed it (see [`pipelineRun`](core.md#pipelinerun)). Where a producer's pipeline execution is itself the natural deployment boundary, its `id` MAY be reused as the `deployment` subject's `id`. + +| Field | Type | Description | Examples | +|-------|------|-------------|----------| +| id | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` | +| source | `URI-Reference` | See [source](spec.md#source-subject) | `/cd/deploy-controller` | +| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | +| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | + ## Events ### [`environment created`](conformance/environment_created.json) @@ -148,6 +160,52 @@ This event represents the removal of a previously deployed service instance and | source | `URI-Reference` | See [source](spec.md#source-subject) | | | | environment | `Object` ([`environment`](#environment)) | Reference for the environment where the service runs | `{"id": "1234"}`, `{"id": "maven123, "source": "tekton-dev-123"}` | ✅ | +### [`deployment queued`](conformance/deployment_queued.json) + +This event represents a deployment that has been accepted and is waiting to begin. + +- Event Type: __`dev.cdevents.deployment.queued.0.1.0`__ +- Predicate: queued +- Subject: [`deployment`](#deployment) + +| Field | Type | Description | Examples | Required | +|-------|------|-------------|----------|----------------------------| +| id | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` | ✅ | +| source | `URI-Reference` | See [source](spec.md#source-subject) | | | +| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | +| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | ✅ | + +### [`deployment started`](conformance/deployment_started.json) + +This event represents a deployment controller that has begun orchestrating a rollout. + +- Event Type: __`dev.cdevents.deployment.started.0.1.0`__ +- Predicate: started +- Subject: [`deployment`](#deployment) + +| Field | Type | Description | Examples | Required | +|-------|------|-------------|----------|----------------------------| +| id | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` | ✅ | +| source | `URI-Reference` | See [source](spec.md#source-subject) | | | +| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | +| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | ✅ | + +### [`deployment finished`](conformance/deployment_finished.json) + +This event represents a deployment that has completed. `deployment.finished` is the orchestration-side completion fact for a deployment, analogous to `build finished` on the CI side, and is kept separate from the entity-side fact carried by `service.deployed`. + +- Event Type: __`dev.cdevents.deployment.finished.0.1.0`__ +- Predicate: finished +- Subject: [`deployment`](#deployment) + +| Field | Type | Description | Examples | Required | +|-------|------|-------------|----------|----------------------------| +| id | `String` | See [id](spec.md#id-subject)| `dep-8f3a2c` | ✅ | +| source | `URI-Reference` | See [source](spec.md#source-subject) | | | +| artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | +| environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | ✅ | +| outcome | `String (enum)` | Outcome of the finished deployment | `success`, `failure`, `cancel`, `error` | ✅ | + ### [`service published`](conformance/service_published.json) This event represents an existing instance of a service that has an accessible URL for users to interact with it. This event can be used to let other tools know that the service is ready and also available for consumption. diff --git a/schemas/_defs/deployment.json b/schemas/_defs/deployment.json new file mode 100644 index 0000000..6bd7d7f --- /dev/null +++ b/schemas/_defs/deployment.json @@ -0,0 +1,16 @@ +{ + "$id": "cdevents/_defs/deployment", + "term": "Deployment", + "definition": "A Deployment is the act of applying a version of a release unit to an environment. A deployment is a canonical SDLC fact, and it is not the pipeline that performed the deployment, but the change to the running system that resulted from it.", + "notes": [ + "A Deployment is not the pipeline or tooling that executed it", + "deployment separates the orchestration act of deploying from the entity fact of a running service, mirroring the build/artifact split in CI" + ], + "examples": [ + "Deploying myapp v1.2.3 to the production environment", + "A Spinnaker pipeline execution that rolls out a service to a Kubernetes cluster" + ], + "counterExamples": [ + "The pipeline that performed the deployment" + ] +} diff --git a/schemas/_defs/finished.json b/schemas/_defs/finished.json new file mode 100644 index 0000000..56001e3 --- /dev/null +++ b/schemas/_defs/finished.json @@ -0,0 +1,20 @@ +{ + "$id": "cdevents/_defs/finished", + "term": "Finished", + "definition": "Indicates that execution of an entity has ended, regardless of outcome. The outcome field on the event conveys whether execution succeeded or failed.", + "notes": [ + "A finished event does not imply successful execution.", + "The outcome field must be inspected to determine success or failure.", + "A finished event is terminal — no further lifecycle events follow for this entity." + ], + "examples": [ + "A deployment completing across all target rollouts", + "A target rollout completing at its destination", + "A pipeline run terminating with success or failure" + ], + "counterExamples": [ + "Intermediate execution states", + "Progress or partial completion signals", + "Cancellation requests (the finished event is emitted after cancellation is complete)" + ] +} diff --git a/schemas/_defs/queued.json b/schemas/_defs/queued.json new file mode 100644 index 0000000..9990d37 --- /dev/null +++ b/schemas/_defs/queued.json @@ -0,0 +1,18 @@ +{ + "$id": "cdevents/_defs/queued", + "term": "Queued", + "definition": "Indicates that an entity has been accepted and is waiting to begin execution.", + "notes": [ + "A queued event does not imply that execution has started.", + "The associated entity may be held by scheduling, resource availability, or dependencies." + ], + "examples": [ + "A deployment accepted by a deploy controller and waiting for resources", + "A target rollout scheduled but not yet executing", + "A pipeline run waiting in a queue before a worker picks it up" + ], + "counterExamples": [ + "Active execution of the entity", + "Completion or failure of the entity" + ] +} diff --git a/schemas/deploymentfinished.json b/schemas/deploymentfinished.json new file mode 100644 index 0000000..f2c2b01 --- /dev/null +++ b/schemas/deploymentfinished.json @@ -0,0 +1,140 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.6.0-draft/schema/deployment-finished-event", + "x-cdevents-semantics": { + "subject": "cdevents/_defs/deployment", + "predicate": "cdevents/_defs/finished" + }, + "properties": { + "context": { + "properties": { + "specversion": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.deployment.finished.0.1.0" + ], + "default": "dev.cdevents.deployment.finished.0.1.0" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "schemaUri": { + "type": "string", + "minLength": 1, + "format": "uri" + }, + "chainId": { + "type": "string", + "minLength": 1 + }, + "links": { + "$ref": "links/embeddedlinksarray" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "specversion", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "content": { + "properties": { + "artifactId": { + "type": "string", + "minLength": 1 + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "outcome": { + "type": "string", + "enum": [ + "success", + "failure", + "cancel", + "error" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "artifactId", + "environment", + "outcome" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} diff --git a/schemas/deploymentqueued.json b/schemas/deploymentqueued.json new file mode 100644 index 0000000..eda11f5 --- /dev/null +++ b/schemas/deploymentqueued.json @@ -0,0 +1,130 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.6.0-draft/schema/deployment-queued-event", + "x-cdevents-semantics": { + "subject": "cdevents/_defs/deployment", + "predicate": "cdevents/_defs/queued" + }, + "properties": { + "context": { + "properties": { + "specversion": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.deployment.queued.0.1.0" + ], + "default": "dev.cdevents.deployment.queued.0.1.0" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "schemaUri": { + "type": "string", + "minLength": 1, + "format": "uri" + }, + "chainId": { + "type": "string", + "minLength": 1 + }, + "links": { + "$ref": "links/embeddedlinksarray" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "specversion", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "content": { + "properties": { + "artifactId": { + "type": "string", + "minLength": 1 + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "artifactId", + "environment" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} diff --git a/schemas/deploymentstarted.json b/schemas/deploymentstarted.json new file mode 100644 index 0000000..0a48df1 --- /dev/null +++ b/schemas/deploymentstarted.json @@ -0,0 +1,130 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.6.0-draft/schema/deployment-started-event", + "x-cdevents-semantics": { + "subject": "cdevents/_defs/deployment", + "predicate": "cdevents/_defs/started" + }, + "properties": { + "context": { + "properties": { + "specversion": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.deployment.started.0.1.0" + ], + "default": "dev.cdevents.deployment.started.0.1.0" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "schemaUri": { + "type": "string", + "minLength": 1, + "format": "uri" + }, + "chainId": { + "type": "string", + "minLength": 1 + }, + "links": { + "$ref": "links/embeddedlinksarray" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "specversion", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "content": { + "properties": { + "artifactId": { + "type": "string", + "minLength": 1 + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "artifactId", + "environment" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} From 254c49db66e4fb2913d78fbf1862b2adf156dc6c Mon Sep 17 00:00:00 2001 From: xibz Date: Thu, 13 Aug 2026 11:40:07 -0500 Subject: [PATCH 2/4] feat(targetrollout): add targetRollout subject and queued/started/finished events Follow-up to the deployment subject: targetRollout models a single destination within a deployment's environment (a region, canary slot, or named blue/green slot), giving environment a first-class inbound link to what was rolled out into it, and giving consumers per- destination outcome/failureType detail when a deployment fans out to more than one target. This mirrors the pipelineRun/taskRun split already in the spec: a parent orchestration entity (deployment/pipelineRun) fans out to child execution units (targetRollout/taskRun), each with the standard queued/started/finished lifecycle. Stacked on the deployment subject (see the deployment branch/PR) since targetRollout's deploymentId reference and docs build on it. Signed-off-by: xibz --- .spellcheck-en-custom.txt | 1 + conformance/targetrollout_finished.json | 25 ++++ conformance/targetrollout_queued.json | 24 ++++ conformance/targetrollout_started.json | 24 ++++ continuous-deployment.md | 79 +++++++++++- schemas/_defs/deployment.json | 12 +- schemas/_defs/targetrollout.json | 20 +++ schemas/targetrolloutfinished.json | 165 ++++++++++++++++++++++++ schemas/targetrolloutqueued.json | 145 +++++++++++++++++++++ schemas/targetrolloutstarted.json | 145 +++++++++++++++++++++ 10 files changed, 631 insertions(+), 9 deletions(-) create mode 100644 conformance/targetrollout_finished.json create mode 100644 conformance/targetrollout_queued.json create mode 100644 conformance/targetrollout_started.json create mode 100644 schemas/_defs/targetrollout.json create mode 100644 schemas/targetrolloutfinished.json create mode 100644 schemas/targetrolloutqueued.json create mode 100644 schemas/targetrolloutstarted.json diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt index 4bb487d..19731b8 100644 --- a/.spellcheck-en-custom.txt +++ b/.spellcheck-en-custom.txt @@ -61,6 +61,7 @@ schemauri specversion src subjectid +targetrollout taskrun testcase testcaserun diff --git a/conformance/targetrollout_finished.json b/conformance/targetrollout_finished.json new file mode 100644 index 0000000..de3b2c4 --- /dev/null +++ b/conformance/targetrollout_finished.json @@ -0,0 +1,25 @@ +{ + "context": { + "specversion": "0.6.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", + "source": "/event/source/123", + "type": "dev.cdevents.targetrollout.finished.0.1.0", + "timestamp": "2023-03-20T14:27:05.315384Z", + "schemaUri": "https://myorg.com/schema/custom" + }, + "subject": { + "id": "mySubject123", + "source": "/event/source/123", + "content": { + "name": "us-east-1", + "target": "cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1", + "environment": { + "id": "test123" + }, + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", + "deploymentId": "mySubject123", + "outcome": "success" + } + } +} diff --git a/conformance/targetrollout_queued.json b/conformance/targetrollout_queued.json new file mode 100644 index 0000000..48c9c42 --- /dev/null +++ b/conformance/targetrollout_queued.json @@ -0,0 +1,24 @@ +{ + "context": { + "specversion": "0.6.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", + "source": "/event/source/123", + "type": "dev.cdevents.targetrollout.queued.0.1.0", + "timestamp": "2023-03-20T14:27:05.315384Z", + "schemaUri": "https://myorg.com/schema/custom" + }, + "subject": { + "id": "mySubject123", + "source": "/event/source/123", + "content": { + "name": "us-east-1", + "target": "cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1", + "environment": { + "id": "test123" + }, + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", + "deploymentId": "mySubject123" + } + } +} diff --git a/conformance/targetrollout_started.json b/conformance/targetrollout_started.json new file mode 100644 index 0000000..9d3f353 --- /dev/null +++ b/conformance/targetrollout_started.json @@ -0,0 +1,24 @@ +{ + "context": { + "specversion": "0.6.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", + "source": "/event/source/123", + "type": "dev.cdevents.targetrollout.started.0.1.0", + "timestamp": "2023-03-20T14:27:05.315384Z", + "schemaUri": "https://myorg.com/schema/custom" + }, + "subject": { + "id": "mySubject123", + "source": "/event/source/123", + "content": { + "name": "us-east-1", + "target": "cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1", + "environment": { + "id": "test123" + }, + "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", + "deploymentId": "mySubject123" + } + } +} diff --git a/continuous-deployment.md b/continuous-deployment.md index 10a73d9..69dd645 100644 --- a/continuous-deployment.md +++ b/continuous-deployment.md @@ -14,13 +14,14 @@ Continuous Deployment (CD) events are related to continuous deployment pipelines ## Subjects -This specification defines three subjects in this stage: `environment`, `service`, and `deployment`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the act of applying a version of a release unit to an environment. +This specification defines four subjects in this stage: `environment`, `service`, `deployment`, and `targetRollout`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the aggregate act of applying a version of a release unit to one or more `targetRollout`s, and a `targetRollout` is a specific destination within an environment to which a release unit is deployed. | Subject | Description | Predicates | |---------|-------------|------------| | [`environment`](#environment) | An environment where to run services | [`created`](#environment-created), [`modified`](#environment-modified), [`deleted`](#environment-deleted)| | [`service`](#service) | A service | [`deployed`](#service-deployed), [`upgraded`](#service-upgraded), [`rolledback`](#service-rolledback), [`removed`](#service-removed), [`published`](#service-published)| -| [`deployment`](#deployment) | The act of deploying a release unit to an environment | [`queued`](#deployment-queued), [`started`](#deployment-started), [`finished`](#deployment-finished)| +| [`deployment`](#deployment) | The aggregate act of deploying a release unit to one or more target rollouts | [`queued`](#deployment-queued), [`started`](#deployment-started), [`finished`](#deployment-finished)| +| [`targetRollout`](#targetrollout) | A specific deployment destination within an environment | [`queued`](#targetrollout-queued), [`started`](#targetrollout-started), [`finished`](#targetrollout-finished)| ### `environment` @@ -46,7 +47,7 @@ A `service` can represent for example a binary that is running, a daemon, an app ### `deployment` -A `deployment` is the act of applying a version of a release unit to an environment. A deployment is a canonical SDLC fact: it represents the change to the running system that resulted from a release, as distinct in meaning from the orchestration that performed it (see [`pipelineRun`](core.md#pipelinerun)). Where a producer's pipeline execution is itself the natural deployment boundary, its `id` MAY be reused as the `deployment` subject's `id`. +A `deployment` is the act of applying a version of a release unit to one or more target rollouts. A deployment is a canonical SDLC fact: it represents the change to the running system that resulted from a release, as distinct in meaning from the orchestration that performed it (see [`pipelineRun`](core.md#pipelinerun)). Where a producer's pipeline execution is itself the natural deployment boundary, its `id` MAY be reused as the `deployment` subject's `id`. A deployment fans out to one or more [`targetRollout`](#targetrollout)s. | Field | Type | Description | Examples | |-------|------|-------------|----------| @@ -55,6 +56,20 @@ A `deployment` is the act of applying a version of a release unit to an environm | artifactId | `Purl` | Identifier of the artifact being deployed | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | | environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | +### `targetRollout` + +A `targetRollout` is a specific destination within an environment to which a release unit may be deployed and made available, for example a Kubernetes namespace in a particular region, or a named blue/green slot. A `targetRollout` is always contained within an environment, and multiple target rollouts may exist within a single environment. Each `targetRollout` carries a `deploymentId` reference back to its parent [`deployment`](#deployment). This also gives [`environment`](#environment) a first-class inbound link to what has been deployed into it: `environment created`/`modified`/`deleted` describe the platform alone, and previously the only way to associate an environment with what is running in it was to inspect `service` events, where the reference points the other way, from the entity back down to the environment it happens to run in. `targetRollout` events point from the act of deploying to the destination, so "what was rolled out to this environment" is a direct query rather than an inference over `service` events. + +| Field | Type | Description | Examples | +|-------|------|-------------|----------| +| id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | +| source | `URI-Reference` | See [source](spec.md#source-subject) | `/cd/deploy-controller` | +| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | +| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | +| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | +| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | +| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | + ## Events ### [`environment created`](conformance/environment_created.json) @@ -192,7 +207,7 @@ This event represents a deployment controller that has begun orchestrating a rol ### [`deployment finished`](conformance/deployment_finished.json) -This event represents a deployment that has completed. `deployment.finished` is the orchestration-side completion fact for a deployment, analogous to `build finished` on the CI side, and is kept separate from the entity-side fact carried by `service.deployed`. +This event represents a deployment that has completed across all of its target rollouts. `deployment.finished` is the orchestration-side completion fact for a deployment, analogous to `build finished` on the CI side, and is kept separate from the entity-side fact carried by `service.deployed`. Failure semantics are all-or-nothing: if any target rollout fails, `deployment.finished` has `outcome: failure`. Consumers needing per-destination detail should inspect the individual [`targetRollout finished`](#targetrollout-finished) events. - Event Type: __`dev.cdevents.deployment.finished.0.1.0`__ - Predicate: finished @@ -206,6 +221,62 @@ This event represents a deployment that has completed. `deployment.finished` is | environment | `Object` ([`environment`](#environment)) | Reference to the target environment | `{"id": "production"}` | ✅ | | outcome | `String (enum)` | Outcome of the finished deployment | `success`, `failure`, `cancel`, `error` | ✅ | +### [`targetRollout queued`](conformance/targetrollout_queued.json) + +This event represents a deployment to a specific target rollout that has been scheduled. + +- Event Type: __`dev.cdevents.targetrollout.queued.0.1.0`__ +- Predicate: queued +- Subject: [`targetRollout`](#targetrollout) + +| Field | Type | Description | Examples | Required | +|-------|------|-------------|----------|----------------------------| +| id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ | +| source | `URI-Reference` | See [source](spec.md#source-subject) | | | +| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | ✅ | +| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | +| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | +| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | +| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | | + +### [`targetRollout started`](conformance/targetrollout_started.json) + +This event represents a deployment to a specific target rollout that has begun. + +- Event Type: __`dev.cdevents.targetrollout.started.0.1.0`__ +- Predicate: started +- Subject: [`targetRollout`](#targetrollout) + +| Field | Type | Description | Examples | Required | +|-------|------|-------------|----------|----------------------------| +| id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ | +| source | `URI-Reference` | See [source](spec.md#source-subject) | | | +| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | ✅ | +| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | +| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | +| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | +| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | | + +### [`targetRollout finished`](conformance/targetrollout_finished.json) + +This event represents a deployment to a specific target rollout that has completed. `failureType` categorizes the failure reason when `outcome` is `failure`, letting consumers distinguish a policy gate, build, evaluation, deployment, or analysis failure without producer-specific convention. + +- Event Type: __`dev.cdevents.targetrollout.finished.0.1.0`__ +- Predicate: finished +- Subject: [`targetRollout`](#targetrollout) + +| Field | Type | Description | Examples | Required | +|-------|------|-------------|----------|----------------------------| +| id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ | +| source | `URI-Reference` | See [source](spec.md#source-subject) | | | +| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | ✅ | +| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | +| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | +| artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | +| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | | +| outcome | `String (enum)` | Outcome of the finished target rollout | `success`, `failure`, `cancel`, `error` | ✅ | +| failureType | `String (enum)` | Category of failure, only present when `outcome` is `failure` | `gate`, `build`, `evaluation`, `deployment`, `analysis` | | + ### [`service published`](conformance/service_published.json) This event represents an existing instance of a service that has an accessible URL for users to interact with it. This event can be used to let other tools know that the service is ready and also available for consumption. diff --git a/schemas/_defs/deployment.json b/schemas/_defs/deployment.json index 6bd7d7f..9feb6d3 100644 --- a/schemas/_defs/deployment.json +++ b/schemas/_defs/deployment.json @@ -1,16 +1,18 @@ { "$id": "cdevents/_defs/deployment", "term": "Deployment", - "definition": "A Deployment is the act of applying a version of a release unit to an environment. A deployment is a canonical SDLC fact, and it is not the pipeline that performed the deployment, but the change to the running system that resulted from it.", + "definition": "A Deployment is the act of applying a version of a release unit to one or more target rollouts. A deployment is a canonical SDLC fact, and it is not the pipeline that performed the deployment, but the change to the running system that resulted from it.", "notes": [ + "A Deployment fans out to one or more TargetRollouts", "A Deployment is not the pipeline or tooling that executed it", - "deployment separates the orchestration act of deploying from the entity fact of a running service, mirroring the build/artifact split in CI" + "deployment/targetRollout separate the orchestration act of deploying from the entity fact of a running service, mirroring the build/artifact split in CI" ], "examples": [ - "Deploying myapp v1.2.3 to the production environment", - "A Spinnaker pipeline execution that rolls out a service to a Kubernetes cluster" + "Deploying myapp v1.2.3 to the production environment across multiple regions", + "A Spinnaker pipeline execution that rolls out a service to multiple Kubernetes clusters" ], "counterExamples": [ - "The pipeline that performed the deployment" + "The pipeline that performed the deployment", + "An individual rollout to a single target (that is a TargetRollout)" ] } diff --git a/schemas/_defs/targetrollout.json b/schemas/_defs/targetrollout.json new file mode 100644 index 0000000..ee1b5cb --- /dev/null +++ b/schemas/_defs/targetrollout.json @@ -0,0 +1,20 @@ +{ + "$id": "cdevents/_defs/targetrollout", + "term": "TargetRollout", + "definition": "A TargetRollout is a specific destination within an environment to which a release unit may be deployed and made available. A TargetRollout is always contained within an environment. Multiple TargetRollouts may exist within a single environment.", + "notes": [ + "A TargetRollout carries a deploymentId reference back to its parent Deployment", + "A TargetRollout represents a single deployment destination, not an environment", + "failureType is available on targetRollout.finished to express per-destination failure reasons", + "TargetRollout gives Environment a first-class inbound link to what was deployed into it, rather than relying on Service's backwards-pointing environment reference" + ], + "examples": [ + "A Kubernetes namespace in us-east-1 within the production environment", + "A canary slot within a blue/green deployment", + "A named deployment slot in a cloud provider region" + ], + "counterExamples": [ + "An environment itself", + "The aggregate deployment across all targets (that is a Deployment)" + ] +} diff --git a/schemas/targetrolloutfinished.json b/schemas/targetrolloutfinished.json new file mode 100644 index 0000000..90200f5 --- /dev/null +++ b/schemas/targetrolloutfinished.json @@ -0,0 +1,165 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.6.0-draft/schema/targetrollout-finished-event", + "x-cdevents-semantics": { + "subject": "cdevents/_defs/targetrollout", + "predicate": "cdevents/_defs/finished" + }, + "properties": { + "context": { + "properties": { + "specversion": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.targetrollout.finished.0.1.0" + ], + "default": "dev.cdevents.targetrollout.finished.0.1.0" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "schemaUri": { + "type": "string", + "minLength": 1, + "format": "uri" + }, + "chainId": { + "type": "string", + "minLength": 1 + }, + "links": { + "$ref": "links/embeddedlinksarray" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "specversion", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "content": { + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "target": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "artifactId": { + "type": "string", + "minLength": 1 + }, + "deploymentId": { + "type": "string", + "minLength": 1 + }, + "outcome": { + "type": "string", + "enum": [ + "success", + "failure", + "cancel", + "error" + ] + }, + "failureType": { + "type": "string", + "enum": [ + "gate", + "build", + "evaluation", + "deployment", + "analysis" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name", + "target", + "environment", + "artifactId", + "outcome" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} diff --git a/schemas/targetrolloutqueued.json b/schemas/targetrolloutqueued.json new file mode 100644 index 0000000..6347d1e --- /dev/null +++ b/schemas/targetrolloutqueued.json @@ -0,0 +1,145 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.6.0-draft/schema/targetrollout-queued-event", + "x-cdevents-semantics": { + "subject": "cdevents/_defs/targetrollout", + "predicate": "cdevents/_defs/queued" + }, + "properties": { + "context": { + "properties": { + "specversion": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.targetrollout.queued.0.1.0" + ], + "default": "dev.cdevents.targetrollout.queued.0.1.0" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "schemaUri": { + "type": "string", + "minLength": 1, + "format": "uri" + }, + "chainId": { + "type": "string", + "minLength": 1 + }, + "links": { + "$ref": "links/embeddedlinksarray" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "specversion", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "content": { + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "target": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "artifactId": { + "type": "string", + "minLength": 1 + }, + "deploymentId": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name", + "target", + "environment", + "artifactId" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} diff --git a/schemas/targetrolloutstarted.json b/schemas/targetrolloutstarted.json new file mode 100644 index 0000000..aa6685e --- /dev/null +++ b/schemas/targetrolloutstarted.json @@ -0,0 +1,145 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.6.0-draft/schema/targetrollout-started-event", + "x-cdevents-semantics": { + "subject": "cdevents/_defs/targetrollout", + "predicate": "cdevents/_defs/started" + }, + "properties": { + "context": { + "properties": { + "specversion": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.targetrollout.started.0.1.0" + ], + "default": "dev.cdevents.targetrollout.started.0.1.0" + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "schemaUri": { + "type": "string", + "minLength": 1, + "format": "uri" + }, + "chainId": { + "type": "string", + "minLength": 1 + }, + "links": { + "$ref": "links/embeddedlinksarray" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "specversion", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "content": { + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "target": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "environment": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id" + ] + }, + "artifactId": { + "type": "string", + "minLength": 1 + }, + "deploymentId": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name", + "target", + "environment", + "artifactId" + ] + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} From 82f1bf37a29501a94d18adaa859e1760a4117f87 Mon Sep 17 00:00:00 2001 From: xibz Date: Tue, 13 Oct 2026 12:03:31 -0500 Subject: [PATCH 3/4] fix(targetrollout): address review feedback - Redefine targetRollout as the act of deploying a release unit to a single destination, not the destination itself. The destination is already identified by the target and environment fields, and the queued/started/finished lifecycle only makes sense for an activity. Examples and counterExamples updated to match. - Make deploymentId required on queued/started/finished: a target rollout is always part of a deployment. - Give the parent deployment a distinct id in the targetRollout conformance examples so it no longer reads as the subject itself. Signed-off-by: xibz --- conformance/targetrollout_finished.json | 2 +- conformance/targetrollout_queued.json | 2 +- conformance/targetrollout_started.json | 2 +- continuous-deployment.md | 12 ++++++------ schemas/_defs/targetrollout.json | 11 ++++++----- schemas/targetrolloutfinished.json | 1 + schemas/targetrolloutqueued.json | 3 ++- schemas/targetrolloutstarted.json | 3 ++- 8 files changed, 20 insertions(+), 16 deletions(-) diff --git a/conformance/targetrollout_finished.json b/conformance/targetrollout_finished.json index de3b2c4..f443e88 100644 --- a/conformance/targetrollout_finished.json +++ b/conformance/targetrollout_finished.json @@ -18,7 +18,7 @@ "id": "test123" }, "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", - "deploymentId": "mySubject123", + "deploymentId": "myDeployment123", "outcome": "success" } } diff --git a/conformance/targetrollout_queued.json b/conformance/targetrollout_queued.json index 48c9c42..7618931 100644 --- a/conformance/targetrollout_queued.json +++ b/conformance/targetrollout_queued.json @@ -18,7 +18,7 @@ "id": "test123" }, "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", - "deploymentId": "mySubject123" + "deploymentId": "myDeployment123" } } } diff --git a/conformance/targetrollout_started.json b/conformance/targetrollout_started.json index 9d3f353..61a718f 100644 --- a/conformance/targetrollout_started.json +++ b/conformance/targetrollout_started.json @@ -18,7 +18,7 @@ "id": "test123" }, "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", - "deploymentId": "mySubject123" + "deploymentId": "myDeployment123" } } } diff --git a/continuous-deployment.md b/continuous-deployment.md index 69dd645..8c0c5fc 100644 --- a/continuous-deployment.md +++ b/continuous-deployment.md @@ -14,14 +14,14 @@ Continuous Deployment (CD) events are related to continuous deployment pipelines ## Subjects -This specification defines four subjects in this stage: `environment`, `service`, `deployment`, and `targetRollout`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the aggregate act of applying a version of a release unit to one or more `targetRollout`s, and a `targetRollout` is a specific destination within an environment to which a release unit is deployed. +This specification defines four subjects in this stage: `environment`, `service`, `deployment`, and `targetRollout`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the aggregate act of applying a version of a release unit to one or more `targetRollout`s, and a `targetRollout` is the act of deploying a release unit to a single destination within an environment. | Subject | Description | Predicates | |---------|-------------|------------| | [`environment`](#environment) | An environment where to run services | [`created`](#environment-created), [`modified`](#environment-modified), [`deleted`](#environment-deleted)| | [`service`](#service) | A service | [`deployed`](#service-deployed), [`upgraded`](#service-upgraded), [`rolledback`](#service-rolledback), [`removed`](#service-removed), [`published`](#service-published)| | [`deployment`](#deployment) | The aggregate act of deploying a release unit to one or more target rollouts | [`queued`](#deployment-queued), [`started`](#deployment-started), [`finished`](#deployment-finished)| -| [`targetRollout`](#targetrollout) | A specific deployment destination within an environment | [`queued`](#targetrollout-queued), [`started`](#targetrollout-started), [`finished`](#targetrollout-finished)| +| [`targetRollout`](#targetrollout) | The rollout of a deployment to a single destination within an environment | [`queued`](#targetrollout-queued), [`started`](#targetrollout-started), [`finished`](#targetrollout-finished)| ### `environment` @@ -58,7 +58,7 @@ A `deployment` is the act of applying a version of a release unit to one or more ### `targetRollout` -A `targetRollout` is a specific destination within an environment to which a release unit may be deployed and made available, for example a Kubernetes namespace in a particular region, or a named blue/green slot. A `targetRollout` is always contained within an environment, and multiple target rollouts may exist within a single environment. Each `targetRollout` carries a `deploymentId` reference back to its parent [`deployment`](#deployment). This also gives [`environment`](#environment) a first-class inbound link to what has been deployed into it: `environment created`/`modified`/`deleted` describe the platform alone, and previously the only way to associate an environment with what is running in it was to inspect `service` events, where the reference points the other way, from the entity back down to the environment it happens to run in. `targetRollout` events point from the act of deploying to the destination, so "what was rolled out to this environment" is a direct query rather than an inference over `service` events. +A `targetRollout` is the act of deploying a release unit to a single destination within an environment, as one part of a [`deployment`](#deployment). The destination itself, for example a Kubernetes namespace in a particular region or a named blue/green slot, is identified by the `target` and `environment` fields. A `targetRollout` is always contained within an environment, and multiple target rollouts may exist within a single environment. Each `targetRollout` carries a `deploymentId` reference back to its parent [`deployment`](#deployment). This also gives [`environment`](#environment) a first-class inbound link to what has been deployed into it: `environment created`/`modified`/`deleted` describe the platform alone, and previously the only way to associate an environment with what is running in it was to inspect `service` events, where the reference points the other way, from the entity back down to the environment it happens to run in. `targetRollout` events point from the act of deploying to the destination, so "what was rolled out to this environment" is a direct query rather than an inference over `service` events. | Field | Type | Description | Examples | |-------|------|-------------|----------| @@ -237,7 +237,7 @@ This event represents a deployment to a specific target rollout that has been sc | target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | | environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | | artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | -| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | | +| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ | ### [`targetRollout started`](conformance/targetrollout_started.json) @@ -255,7 +255,7 @@ This event represents a deployment to a specific target rollout that has begun. | target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | | environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | | artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | -| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | | +| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ | ### [`targetRollout finished`](conformance/targetrollout_finished.json) @@ -273,7 +273,7 @@ This event represents a deployment to a specific target rollout that has complet | target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | | environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | | artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | -| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | | +| deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ | | outcome | `String (enum)` | Outcome of the finished target rollout | `success`, `failure`, `cancel`, `error` | ✅ | | failureType | `String (enum)` | Category of failure, only present when `outcome` is `failure` | `gate`, `build`, `evaluation`, `deployment`, `analysis` | | diff --git a/schemas/_defs/targetrollout.json b/schemas/_defs/targetrollout.json index ee1b5cb..a85dcc6 100644 --- a/schemas/_defs/targetrollout.json +++ b/schemas/_defs/targetrollout.json @@ -1,20 +1,21 @@ { "$id": "cdevents/_defs/targetrollout", "term": "TargetRollout", - "definition": "A TargetRollout is a specific destination within an environment to which a release unit may be deployed and made available. A TargetRollout is always contained within an environment. Multiple TargetRollouts may exist within a single environment.", + "definition": "A TargetRollout is the act of deploying a release unit to a single destination within an environment, as one part of a Deployment. The destination itself is identified by the TargetRollout's target and environment.", "notes": [ "A TargetRollout carries a deploymentId reference back to its parent Deployment", - "A TargetRollout represents a single deployment destination, not an environment", + "A TargetRollout represents the rollout to a single destination, not the destination itself", "failureType is available on targetRollout.finished to express per-destination failure reasons", "TargetRollout gives Environment a first-class inbound link to what was deployed into it, rather than relying on Service's backwards-pointing environment reference" ], "examples": [ - "A Kubernetes namespace in us-east-1 within the production environment", - "A canary slot within a blue/green deployment", - "A named deployment slot in a cloud provider region" + "Rolling myapp@sha256:0b31b1c0 out to a Kubernetes namespace in us-east-1 within the production environment", + "Shifting a canary slot to a new version as part of a blue/green deployment", + "Deploying a release to a named deployment slot in a cloud provider region" ], "counterExamples": [ "An environment itself", + "A destination such as a namespace, region or canary slot (that is the target)", "The aggregate deployment across all targets (that is a Deployment)" ] } diff --git a/schemas/targetrolloutfinished.json b/schemas/targetrolloutfinished.json index 90200f5..92b2ae0 100644 --- a/schemas/targetrolloutfinished.json +++ b/schemas/targetrolloutfinished.json @@ -130,6 +130,7 @@ "target", "environment", "artifactId", + "deploymentId", "outcome" ] } diff --git a/schemas/targetrolloutqueued.json b/schemas/targetrolloutqueued.json index 6347d1e..10e9bc9 100644 --- a/schemas/targetrolloutqueued.json +++ b/schemas/targetrolloutqueued.json @@ -110,7 +110,8 @@ "name", "target", "environment", - "artifactId" + "artifactId", + "deploymentId" ] } }, diff --git a/schemas/targetrolloutstarted.json b/schemas/targetrolloutstarted.json index aa6685e..53a9019 100644 --- a/schemas/targetrolloutstarted.json +++ b/schemas/targetrolloutstarted.json @@ -110,7 +110,8 @@ "name", "target", "environment", - "artifactId" + "artifactId", + "deploymentId" ] } }, From 9711ab3f4295419355782b61f4cb15de9a57cf39 Mon Sep 17 00:00:00 2001 From: xibz Date: Wed, 14 Oct 2026 09:08:04 -0500 Subject: [PATCH 4/4] fix(targetrollout): address second round of review feedback - Remove name: the rollout is identified by subject.id, like deployment, and the destination by target. - Replace the environment reference with tier (the logical environment, used to compute lead time to deploy); target is the concrete destination within it, typically a cluster. - Reword the definition: the act of deploying an artifact against a destination in a tier. - Version the new targetRollout events 0.1.0-draft and replace "release unit" with "artifact", matching the deployment review. Signed-off-by: xibz --- conformance/targetrollout_finished.json | 9 +++---- conformance/targetrollout_queued.json | 9 +++---- conformance/targetrollout_started.json | 9 +++---- continuous-deployment.md | 32 +++++++++++-------------- schemas/_defs/targetrollout.json | 10 ++++---- schemas/targetrolloutfinished.json | 31 +++++------------------- schemas/targetrolloutqueued.json | 31 +++++------------------- schemas/targetrolloutstarted.json | 31 +++++------------------- 8 files changed, 46 insertions(+), 116 deletions(-) diff --git a/conformance/targetrollout_finished.json b/conformance/targetrollout_finished.json index f443e88..236af38 100644 --- a/conformance/targetrollout_finished.json +++ b/conformance/targetrollout_finished.json @@ -4,7 +4,7 @@ "id": "271069a8-fc18-44f1-b38f-9d70a1695819", "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", "source": "/event/source/123", - "type": "dev.cdevents.targetrollout.finished.0.1.0", + "type": "dev.cdevents.targetrollout.finished.0.1.0-draft", "timestamp": "2023-03-20T14:27:05.315384Z", "schemaUri": "https://myorg.com/schema/custom" }, @@ -12,11 +12,8 @@ "id": "mySubject123", "source": "/event/source/123", "content": { - "name": "us-east-1", - "target": "cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1", - "environment": { - "id": "test123" - }, + "target": "cdevents:v0:argo::my-org:production:cluster:prod-us-east-1", + "tier": "production", "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", "deploymentId": "myDeployment123", "outcome": "success" diff --git a/conformance/targetrollout_queued.json b/conformance/targetrollout_queued.json index 7618931..f04ee60 100644 --- a/conformance/targetrollout_queued.json +++ b/conformance/targetrollout_queued.json @@ -4,7 +4,7 @@ "id": "271069a8-fc18-44f1-b38f-9d70a1695819", "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", "source": "/event/source/123", - "type": "dev.cdevents.targetrollout.queued.0.1.0", + "type": "dev.cdevents.targetrollout.queued.0.1.0-draft", "timestamp": "2023-03-20T14:27:05.315384Z", "schemaUri": "https://myorg.com/schema/custom" }, @@ -12,11 +12,8 @@ "id": "mySubject123", "source": "/event/source/123", "content": { - "name": "us-east-1", - "target": "cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1", - "environment": { - "id": "test123" - }, + "target": "cdevents:v0:argo::my-org:production:cluster:prod-us-east-1", + "tier": "production", "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", "deploymentId": "myDeployment123" } diff --git a/conformance/targetrollout_started.json b/conformance/targetrollout_started.json index 61a718f..2739a35 100644 --- a/conformance/targetrollout_started.json +++ b/conformance/targetrollout_started.json @@ -4,7 +4,7 @@ "id": "271069a8-fc18-44f1-b38f-9d70a1695819", "chainId": "4c8cb7dd-3448-41de-8768-eec704e2829b", "source": "/event/source/123", - "type": "dev.cdevents.targetrollout.started.0.1.0", + "type": "dev.cdevents.targetrollout.started.0.1.0-draft", "timestamp": "2023-03-20T14:27:05.315384Z", "schemaUri": "https://myorg.com/schema/custom" }, @@ -12,11 +12,8 @@ "id": "mySubject123", "source": "/event/source/123", "content": { - "name": "us-east-1", - "target": "cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1", - "environment": { - "id": "test123" - }, + "target": "cdevents:v0:argo::my-org:production:cluster:prod-us-east-1", + "tier": "production", "artifactId": "pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427", "deploymentId": "myDeployment123" } diff --git a/continuous-deployment.md b/continuous-deployment.md index 8c0c5fc..2584952 100644 --- a/continuous-deployment.md +++ b/continuous-deployment.md @@ -14,14 +14,14 @@ Continuous Deployment (CD) events are related to continuous deployment pipelines ## Subjects -This specification defines four subjects in this stage: `environment`, `service`, `deployment`, and `targetRollout`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the aggregate act of applying a version of a release unit to one or more `targetRollout`s, and a `targetRollout` is the act of deploying a release unit to a single destination within an environment. +This specification defines four subjects in this stage: `environment`, `service`, `deployment`, and `targetRollout`. The term `service` is used to represent a running Artifact. A `service` can represent a binary that is running, a daemon, an application, a docker container. The term `environment` represent any platform which has all the means to run a `service`. A `deployment` is the aggregate act of applying a version of a release unit to one or more `targetRollout`s, and a `targetRollout` is the act of deploying an artifact to a single destination within a tier. | Subject | Description | Predicates | |---------|-------------|------------| | [`environment`](#environment) | An environment where to run services | [`created`](#environment-created), [`modified`](#environment-modified), [`deleted`](#environment-deleted)| | [`service`](#service) | A service | [`deployed`](#service-deployed), [`upgraded`](#service-upgraded), [`rolledback`](#service-rolledback), [`removed`](#service-removed), [`published`](#service-published)| | [`deployment`](#deployment) | The aggregate act of deploying a release unit to one or more target rollouts | [`queued`](#deployment-queued), [`started`](#deployment-started), [`finished`](#deployment-finished)| -| [`targetRollout`](#targetrollout) | The rollout of a deployment to a single destination within an environment | [`queued`](#targetrollout-queued), [`started`](#targetrollout-started), [`finished`](#targetrollout-finished)| +| [`targetRollout`](#targetrollout) | The rollout of a deployment to a single destination within a tier | [`queued`](#targetrollout-queued), [`started`](#targetrollout-started), [`finished`](#targetrollout-finished)| ### `environment` @@ -58,15 +58,14 @@ A `deployment` is the act of applying a version of a release unit to one or more ### `targetRollout` -A `targetRollout` is the act of deploying a release unit to a single destination within an environment, as one part of a [`deployment`](#deployment). The destination itself, for example a Kubernetes namespace in a particular region or a named blue/green slot, is identified by the `target` and `environment` fields. A `targetRollout` is always contained within an environment, and multiple target rollouts may exist within a single environment. Each `targetRollout` carries a `deploymentId` reference back to its parent [`deployment`](#deployment). This also gives [`environment`](#environment) a first-class inbound link to what has been deployed into it: `environment created`/`modified`/`deleted` describe the platform alone, and previously the only way to associate an environment with what is running in it was to inspect `service` events, where the reference points the other way, from the entity back down to the environment it happens to run in. `targetRollout` events point from the act of deploying to the destination, so "what was rolled out to this environment" is a direct query rather than an inference over `service` events. +A `targetRollout` is the act of deploying an artifact against a destination in a tier, as one part of a [`deployment`](#deployment). The destination itself, for example a regional cluster within the `production` tier or a named blue/green slot, is identified by `target`, and the logical environment it belongs to by `tier`. Multiple target rollouts may exist within a single tier. Each `targetRollout` carries a `deploymentId` reference back to its parent [`deployment`](#deployment). Together, `tier` and `target` make "what was rolled out to production, and where" a direct query over `targetRollout` events. Previously it had to be inferred from `service` events, whose `environment` reference points the other way, from the running entity back to whatever platform it happens to run on. | Field | Type | Description | Examples | |-------|------|-------------|----------| | id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | | source | `URI-Reference` | See [source](spec.md#source-subject) | `/cd/deploy-controller` | -| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | -| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | -| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | +| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` | +| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` | | artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | | deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | @@ -225,7 +224,7 @@ This event represents a deployment that has completed across all of its target r This event represents a deployment to a specific target rollout that has been scheduled. -- Event Type: __`dev.cdevents.targetrollout.queued.0.1.0`__ +- Event Type: __`dev.cdevents.targetrollout.queued.0.1.0-draft`__ - Predicate: queued - Subject: [`targetRollout`](#targetrollout) @@ -233,9 +232,8 @@ This event represents a deployment to a specific target rollout that has been sc |-------|------|-------------|----------|----------------------------| | id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ | | source | `URI-Reference` | See [source](spec.md#source-subject) | | | -| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | ✅ | -| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | -| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | +| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` | ✅ | +| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` | ✅ | | artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | | deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ | @@ -243,7 +241,7 @@ This event represents a deployment to a specific target rollout that has been sc This event represents a deployment to a specific target rollout that has begun. -- Event Type: __`dev.cdevents.targetrollout.started.0.1.0`__ +- Event Type: __`dev.cdevents.targetrollout.started.0.1.0-draft`__ - Predicate: started - Subject: [`targetRollout`](#targetrollout) @@ -251,9 +249,8 @@ This event represents a deployment to a specific target rollout that has begun. |-------|------|-------------|----------|----------------------------| | id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ | | source | `URI-Reference` | See [source](spec.md#source-subject) | | | -| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | ✅ | -| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | -| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | +| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` | ✅ | +| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` | ✅ | | artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | | deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ | @@ -261,7 +258,7 @@ This event represents a deployment to a specific target rollout that has begun. This event represents a deployment to a specific target rollout that has completed. `failureType` categorizes the failure reason when `outcome` is `failure`, letting consumers distinguish a policy gate, build, evaluation, deployment, or analysis failure without producer-specific convention. -- Event Type: __`dev.cdevents.targetrollout.finished.0.1.0`__ +- Event Type: __`dev.cdevents.targetrollout.finished.0.1.0-draft`__ - Predicate: finished - Subject: [`targetRollout`](#targetrollout) @@ -269,9 +266,8 @@ This event represents a deployment to a specific target rollout that has complet |-------|------|-------------|----------|----------------------------| | id | `String` | See [id](spec.md#id-subject)| `rt-us-east-1-8f3a2c` | ✅ | | source | `URI-Reference` | See [source](spec.md#source-subject) | | | -| name | `String` | Name of the target rollout | `canary`, `us-east-1`, `blue-slot` | ✅ | -| target | `URI-Reference` | Location identifier of where the artifact is being deployed to | `cdevents:v0:argo::my-org:prod-cluster:environment:us-east-1` | ✅ | -| environment | `Object` ([`environment`](#environment)) | Reference to the containing environment | `{"id": "production"}` | ✅ | +| target | `URI-Reference` | Identifier of the concrete destination within the `tier` that this rollout deploys to, for example a regional cluster within `production`. Opaque to CDEvents, but it must identify a destination belonging to that tier | `cdevents:v0:argo::my-org:production:cluster:prod-us-east-1` | ✅ | +| tier | `String` | The logical environment this rollout deploys into, used to compute lead time to deploy. See [tier](schemas/_defs/tier.json) | `production`, `staging`, `development` | ✅ | | artifactId | `Purl` | Identifier of the artifact being deployed to this target | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427` | ✅ | | deploymentId | `String` | Reference to the parent [`deployment`](#deployment) | `dep-8f3a2c` | ✅ | | outcome | `String (enum)` | Outcome of the finished target rollout | `success`, `failure`, `cancel`, `error` | ✅ | diff --git a/schemas/_defs/targetrollout.json b/schemas/_defs/targetrollout.json index a85dcc6..f429bf9 100644 --- a/schemas/_defs/targetrollout.json +++ b/schemas/_defs/targetrollout.json @@ -1,21 +1,21 @@ { "$id": "cdevents/_defs/targetrollout", "term": "TargetRollout", - "definition": "A TargetRollout is the act of deploying a release unit to a single destination within an environment, as one part of a Deployment. The destination itself is identified by the TargetRollout's target and environment.", + "definition": "A TargetRollout is the act of deploying an artifact against a destination in a tier, as one part of a Deployment. The destination itself is identified by the TargetRollout's target, and the logical environment it belongs to by its tier.", "notes": [ "A TargetRollout carries a deploymentId reference back to its parent Deployment", "A TargetRollout represents the rollout to a single destination, not the destination itself", "failureType is available on targetRollout.finished to express per-destination failure reasons", - "TargetRollout gives Environment a first-class inbound link to what was deployed into it, rather than relying on Service's backwards-pointing environment reference" + "TargetRollout makes \"what was rolled out to a tier, and where\" a direct query, rather than an inference over Service's backwards-pointing environment reference" ], "examples": [ - "Rolling myapp@sha256:0b31b1c0 out to a Kubernetes namespace in us-east-1 within the production environment", + "Rolling myapp@sha256:0b31b1c0 out to the us-east-1 cluster within the production tier", "Shifting a canary slot to a new version as part of a blue/green deployment", "Deploying a release to a named deployment slot in a cloud provider region" ], "counterExamples": [ - "An environment itself", - "A destination such as a namespace, region or canary slot (that is the target)", + "A tier itself", + "A destination such as a cluster, region or canary slot (that is the target)", "The aggregate deployment across all targets (that is a Deployment)" ] } diff --git a/schemas/targetrolloutfinished.json b/schemas/targetrolloutfinished.json index 92b2ae0..3d6c3f5 100644 --- a/schemas/targetrolloutfinished.json +++ b/schemas/targetrolloutfinished.json @@ -24,9 +24,9 @@ "type": { "type": "string", "enum": [ - "dev.cdevents.targetrollout.finished.0.1.0" + "dev.cdevents.targetrollout.finished.0.1.0-draft" ], - "default": "dev.cdevents.targetrollout.finished.0.1.0" + "default": "dev.cdevents.targetrollout.finished.0.1.0-draft" }, "timestamp": { "type": "string", @@ -68,32 +68,14 @@ }, "content": { "properties": { - "name": { - "type": "string", - "minLength": 1 - }, "target": { "type": "string", "minLength": 1, "format": "uri-reference" }, - "environment": { - "properties": { - "id": { - "type": "string", - "minLength": 1 - }, - "source": { - "type": "string", - "minLength": 1, - "format": "uri-reference" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "id" - ] + "tier": { + "type": "string", + "minLength": 1 }, "artifactId": { "type": "string", @@ -126,9 +108,8 @@ "additionalProperties": false, "type": "object", "required": [ - "name", "target", - "environment", + "tier", "artifactId", "deploymentId", "outcome" diff --git a/schemas/targetrolloutqueued.json b/schemas/targetrolloutqueued.json index 10e9bc9..7af8b7f 100644 --- a/schemas/targetrolloutqueued.json +++ b/schemas/targetrolloutqueued.json @@ -24,9 +24,9 @@ "type": { "type": "string", "enum": [ - "dev.cdevents.targetrollout.queued.0.1.0" + "dev.cdevents.targetrollout.queued.0.1.0-draft" ], - "default": "dev.cdevents.targetrollout.queued.0.1.0" + "default": "dev.cdevents.targetrollout.queued.0.1.0-draft" }, "timestamp": { "type": "string", @@ -68,32 +68,14 @@ }, "content": { "properties": { - "name": { - "type": "string", - "minLength": 1 - }, "target": { "type": "string", "minLength": 1, "format": "uri-reference" }, - "environment": { - "properties": { - "id": { - "type": "string", - "minLength": 1 - }, - "source": { - "type": "string", - "minLength": 1, - "format": "uri-reference" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "id" - ] + "tier": { + "type": "string", + "minLength": 1 }, "artifactId": { "type": "string", @@ -107,9 +89,8 @@ "additionalProperties": false, "type": "object", "required": [ - "name", "target", - "environment", + "tier", "artifactId", "deploymentId" ] diff --git a/schemas/targetrolloutstarted.json b/schemas/targetrolloutstarted.json index 53a9019..c5fa95c 100644 --- a/schemas/targetrolloutstarted.json +++ b/schemas/targetrolloutstarted.json @@ -24,9 +24,9 @@ "type": { "type": "string", "enum": [ - "dev.cdevents.targetrollout.started.0.1.0" + "dev.cdevents.targetrollout.started.0.1.0-draft" ], - "default": "dev.cdevents.targetrollout.started.0.1.0" + "default": "dev.cdevents.targetrollout.started.0.1.0-draft" }, "timestamp": { "type": "string", @@ -68,32 +68,14 @@ }, "content": { "properties": { - "name": { - "type": "string", - "minLength": 1 - }, "target": { "type": "string", "minLength": 1, "format": "uri-reference" }, - "environment": { - "properties": { - "id": { - "type": "string", - "minLength": 1 - }, - "source": { - "type": "string", - "minLength": 1, - "format": "uri-reference" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "id" - ] + "tier": { + "type": "string", + "minLength": 1 }, "artifactId": { "type": "string", @@ -107,9 +89,8 @@ "additionalProperties": false, "type": "object", "required": [ - "name", "target", - "environment", + "tier", "artifactId", "deploymentId" ]