feat(deployment): add deployment and targetRollout subjects and events

.spellcheck-en-custom.txt

@@ -61,6 +61,7 @@ schemauri
 specversion
 src
 subjectid
+targetrollout
 taskrun
 testcase
 testcaserun

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"
+    }
+  }
+}

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"
+      }
+    }
+  }
+}

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"
+      }
+    }
+  }
+}

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"
+    }
+  }
+}

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"
+    }
+  }
+}

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"
+    }
+  }
+}

continuous-deployment.md

@@ -14,12 +14,14 @@ 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 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 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`
 
@@ -43,6 +45,31 @@ 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 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 |
+|-------|------|-------------|----------|
+| 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"}` |
+
+### `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)
@@ -91,7 +118,9 @@ This event represents an environment that has been deleted.```
 
 ### [`service deployed`](conformance/service_deployed.json)
 
-This event represents a new instance of a service that has been deployed
+This event represents a new instance of a service that has been deployed.
+
+> **Deprecation notice:** `service.deployed` conflates two distinct concerns in a single event: the orchestration act of deploying (which target, whether it succeeded) and the entity fact that results from it (a service instance now running). No other CD/CI subject pair does this — `build`/`taskRun` carry the orchestration side, `artifact`/`service` carry the entity side. `deployment`/`targetRollout` restore that separation. New producers should prefer `deployment.finished`/`targetRollout.finished` for the orchestration fact; `service.deployed` is retained for backwards compatibility as the entity-side fact.
 
 - Event Type: __`dev.cdevents.service.deployed.0.3.0`__
 - Predicate: deployed
@@ -108,6 +137,8 @@ This event represents a new instance of a service that has been deployed
 
 This event represents an existing instance of a service that has been upgraded to a new version
 
+> **Deprecation notice:** `service.upgraded` has the same conflation problem as `service.deployed`: it mixes the orchestration act of rolling out a new version with the entity fact that a service instance is now running it. New producers should prefer `deployment.finished`/`targetRollout.finished` for the orchestration fact; `service.upgraded` is retained for backwards compatibility as the entity-side fact.
+
 - Event Type: __`dev.cdevents.service.upgraded.0.3.0`__
 - Predicate: upgraded
 - Subject: [`service`](#service)
@@ -148,6 +179,108 @@ 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 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
+- 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` | ✅ |
+
+### [`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.