[xibz]

Follow-up to #319 (deployment.queued/started/finished), per @afrittoli's review: landing deployment on its own first, with targetRollout proposed separately here now that there's a concrete use case and one open PR of implementation experience to point to.

What this adds

targetRollout — the act of deploying a release unit against a single destination within a tier (for example the us-east-1 cluster within production, or a named blue/green slot), as one part of a deployment. It has the standard queued/started/finished lifecycle, a required deploymentId back-reference to its parent deployment, and failureType on finished for per-destination failure detail.

Each targetRollout carries:

• tier — the logical environment (production, staging, …) the rollout belongs to: the value consumers key on to compute lead time to deploy. Defined in schemas/_defs/tier.json (introduced in feat(deployment): add deployment subject and queued/started/finished events #319).
• target — the concrete destination within that tier, typically a cluster.

Why tier and not environment

The environment subject is defined as "a platform which may run a service", and in practice it is widely used to mean a specific cluster. Using it for the logical environment made "target is a location within the environment" read as "a cluster within a cluster". Rather than redefine an existing subject, the logical concept gets its own name, and the environment subject section points to tier for anyone looking for it.

Why this isn't a new execution model

The concern raised on #319 was that giving targetRollout its own independent lifecycle "encodes one execution model." But this is the same shape the spec already has for pipelineRun/taskRun: a parent orchestration entity fans out to child execution units, each with its own queued/started/finished. targetRollout under deployment is that same pattern, not a new one. A producer that genuinely fans a deployment out to multiple destinations already has to track per-destination timing to coordinate the rollout in the first place — this just gives that internal fact a standard external shape. A producer that deploys to exactly one destination, or that calls a single atomic multi-region API with no per-destination visibility, simply doesn't emit targetRollout — same as any other optional CDEvents subject.

Together, tier and target also make "what was rolled out to production, and where" a direct query over targetRollout events. Today it has 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.

Depends on #319 — this diff will be just the targetRollout additions once that merges.

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has the primer doc been updated if a design decision is involved
• Have the JSON schemas been updated if the specification changed
• Has spec version and event versions been updated according to the versioning policy
• Meets the CDEvents contributor standards

[afrittoli]

I'm confused here. I thought a TargetRollout was an activity that can be queued, started and finished . In here it is defined as a destination, which seems inconsistent. Can you clarify?

[xibz]

Good catch! The definition was wrong, not the model. A targetRollout is the activity: rolling a deployment out to one target within an environment. The destination itself is already captured by target and environment. I've reworded the definition, examples, and counterExamples accordingly (and moved "a canary slot" to counterExamples, since that's the place, not the rollout). I'd rather not rename to targetRolloutRun: unlike pipeline, there's no static "rollout" definition entity for the Run to distinguish from, "rollout", like "deployment", already names the act.

[afrittoli]

I was expecting the deploymentId to be required. Could you describe a use case where it would not be set?

[xibz]

Agreed, I couldn't come up with a solid case for a rollout without a parent deployment. A producer with a single destination and no aggregate can just emit deployment events. deploymentId is now required on queued, started and finished.

[afrittoli]

NIT: this could be:

  "required": ["name", "target", "environment", "artifactId", "outcome"],
  "if":   { "properties": { "outcome": { "const": "failure" } } },
  "then": { "required": ["failureType"] },
  "else": { "not": { "required": ["failureType"] } }

to enforce that failureType must be there in case of failure and must not be there in case of success.
That said, we don't have that in other schemas, although it would be nice to add.

[xibz]

I like it, but since no other schema uses conditional validation yet, I'd rather not make this one the odd one out. I'll open a follow-up that applies it across all outcome-bearing schemas together. That follow-up also needs to settle whether failureType should be allowed with outcome: error (your else branch would reject it).

[afrittoli]

Shouldn't this be different from the subject.id? I think having the same value is confusing.

[xibz]

Agreed, that made the example read as if the rollout were the deployment. The parent now has its own id (myDeployment123) in all three targetrollout_* conformance examples.

[xibz]

@afrittoli - thanks Andreaa! Can you take a look again?

[afrittoli]

Thanks for the updates, I still have some questions, I'm sorry I missed this in the initial review.

[afrittoli]

The name here still seems to refer to the targetRollout as being a place rather than an activity

[xibz]

Agreed, name was a leftover. The rollout is identified by subject.id, the same way deployment is, and the destination by target. I've removed name from the subject, all three predicates and the conformance examples.

[afrittoli]

I would say the deployment is performed against a destination environment, or a destination in an environment.

[xibz]

That reads better, thanks. I've adopted it, with one change explained in the next thread: it now reads "the act of deploying a release unit against a destination in a tier, as one part of a Deployment."

[afrittoli]

The relationship between target and environment is a bit unclear to me.
The latter is a reference to an environment, the subject in CDEvents, which is clear.
The target I guess represents a specific location within that environment, is that correct?
Is there any connection between the data in the URI-reference and that in the environment?

[xibz]

You've put your finger on the real problem. The field was meant to be the logical environment (production), because it's what consumers key on to compute lead time to deploy. But the environment subject is defined as "a platform which may run a service", and in practice it's widely used to mean a specific cluster. So "target is a location within the environment" reasonably reads as "a cluster within a cluster".

Rather than redefine environment, I've given the logical concept its own name: tier (a string, e.g. production, staging), defined in schemas/_defs/tier.json. target is the concrete destination within that tier, e.g. the us-east-1 cluster that's part of production. One tier contains many targets, and a deployment to production fans out into one targetRollout per target. target is opaque to CDEvents, but it must identify a destination belonging to the tier.

The same rename applies to deployment in #319, and the environment subject section now points to tier for anyone looking for the logical environment. The example is consistent too: "tier": "production" with target: cdevents:v0:argo::my-org:production:cluster:prod-us-east-1.