Skip to content

update(schemas): relax environment id requirement in service upgraded#309

Open
xibz wants to merge 1 commit into
cdevents:mainfrom
xibz:env
Open

update(schemas): relax environment id requirement in service upgraded#309
xibz wants to merge 1 commit into
cdevents:mainfrom
xibz:env

Conversation

@xibz

@xibz xibz commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

Problem

The environment object in serviceUpgraded (and related service events) currently requires an id field. This creates a real-world problem for CD tools that have no concept of a named environment, but they are forced to populate id with a meaningless placeholder like "n/a".

Environment vs. Cluster conflation

Many CD tools (e.g. Spinnaker) operate at the cluster or namespace level, not the environment level. In these systems, a deployment target is a:

cluster — a concrete infrastructure resource — not an abstract environment like "production" or "staging". These concepts are often conflated:

  • A team may deploy the same service to us-east-1-prod and eu-west-1-prod, both of which are "production" environments, but represented as
    distinct clusters with no shared environment identifier.
  • Other tools model environment purely by name convention (prod, nonprod) with no stable ID to reference.

Requiring id forces these tools to either fabricate an identifier or skip the field entirely by violating the schema, neither of which is useful for consumers of the event. We need to be VERY clear on what is an environment and what is a cluster or target. Blending environment to mean cluster is ambiguous. This is out of scope for this PR, but needs to be addressed in the future, see #310

Changes

  • Adds a name field to the environment object with x-suggested-values: [prod, nonprod, unknown] to provide loose governance without
    restricting the field to an enum.
  • Relaxes the required: [id] constraint to anyOf: [{required: [id]}, {required: [name]}], so producers must supply at least one of id or
    name but not necessarily both.

This allows tools like Spinnaker to emit a meaningful name (e.g. "prod") without needing a stable environment id, while tools that do have environment IDs continue to work as before.

@xibz xibz requested a review from a team as a code owner June 5, 2026 15:45
@davidB

davidB commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

An environment in the target place where a service can be deployed (aka VPC, k8s cluster, Nomad cluster, maybe a namespace in a cluster). Often, teams have a naming convention to identify environments in their infrastructure, using a separator (-, /, ':') to compose the name with information, like variant/team, region, audience (dev, uat, prod, ...).

The field is id (and optional source) because it's a way to link to the environment subject (if it exists). So, it's the common issue of identifying the relationship between entities.

TBH, in my use case, I don't have any environment subjects (tools extrapolate the existence from the relation), I used "environment" to point to named cluster. The audience (dev, prod, demo) is part of the id.

  • In a multi-cluster per audience environment, knowing in which cluster(region) a service is deployed is more valuable than the generic audience.
  • When a service is deployed, tools also know on which environment/cluster trigger some complementary action (test, audit, configuration, ...)

IMHO, introducing name doesn't solve the problem, but increases the confusion. For me, name and id are the same, name is an alias to id used by humans.

This fix addresses the docs saying each service event includes
environments, but only has `id` and `source`. This fix ensures that the
events match the docs.

Signed-off-by: xibz <bjp@apple.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants