Resources / PlatformRelease

PlatformRelease

The desired build of every component of the platform, for one commit. The active release is what the platform converges to: gates first, then each component through a canary, a bake and a promotion, with automatic rollback when its objective burns (spec 0047 section 3).

Overview

APIplatform.etorm.com/v1alpha1
Resourceplatformreleases (cluster-scoped inside its cluster)
Short namesprel
Available inthe platform and project clusters
Statuswritten by a controller through /status

Minimal example

apiVersion: platform.etorm.com/v1alpha1
kind: PlatformRelease
metadata:
  name: example
spec:
  commit: "<commit>"
  repository:
    name: "<name>"
  components:
  - name: "<name>"
    kind: Worker
    artifact: {}

Spec

FieldTypeRequiredDefaultAllowedDescription
commitstringyeslength 40 to 40The full source commit id of this release.
activebooleanfalseWhether the platform converges to this release. At most one release is active.
repositoryobjectyesThe Forge repository whose Checks gate the release.
repository.namestringyesName of the Repository.
repository.clusterstring"platform"Cluster of the repository (the platform system project by default).
gateslist of stringup to 32 itemsNames of the Checks that must be `success` on the commit before anything is deployed.
componentslist of objectyesup to 64 itemsOne entry per component.
components[].namestringyeslength 1 to 63Component name, for example api, operator, auth, console.
components[].kindstring (one of)yesWorker, StaticSite, Agent, NodeImage, ComputeProgramWhat kind of thing it is.
components[].artifactobjectyesThe build that CI produced for this commit.
components[].artifact.versionIdstringup to 128 charactersThe identifier of an already uploaded version (for a Worker, the version id the build was uploaded as). Leave it out when the artifact is a bundle: the controller uploads it and records the version it made.
components[].artifact.sourceobjectWhere CI stored the bundle (a Storage bucket).
components[].artifact.source.projectstringup to 63 charactersThe project of the bucket (default platform).
components[].artifact.source.bucketstringup to 63 charactersThe bucket.
components[].artifact.source.keystringup to 512 charactersThe object key, for example workers/status/<sha256>.json.
components[].artifact.digeststringup to 128 charactersContent digest of the artifact.
components[].artifact.buildstringup to 64 charactersThe build id baked into the artifact (what the component reports as running).
components[].artifact.trustedKeystringup to 64 charactersFor a node image: the hex Ed25519 public key it was compiled to trust (spec 0038 section 21).
components[].artifact.featureslist of stringFor a node image: what its node OS can do beyond boot (live-config, spec 0038 section 5).
components[].rolloutobjectHow the component is rolled out.
components[].rollout.canaryPercentinteger51 to 50The share of traffic (or of hosts) that gets the new version first.
components[].rollout.bakeSecondsinteger6000 to 86400How long the canary is watched before promotion.
components[].rollout.settleSecondsinteger18000 to 86400How long after promotion a burning objective still rolls the component back.
components[].rollout.graceSecondsinteger00 to 86400How long after the canary starts a failing intent is forgiven (a station image replaces a machine, which takes minutes).
components[].rollout.requireReadybooleanfalsePositive evidence: promote only while the intent is Ready, move the canary back (and open an Incident) when it is not Ready by maxBakeSeconds, and, with settleIntentRef, move the component back when that intent is not Ready when the settle time ends.
components[].rollout.maxBakeSecondsinteger0 to 604800With requireReady: how long the canary waits for its evidence (default four bakes, at least an hour).
components[].rollout.settleIntentRefobjectWith requireReady: the intent that must be Ready when the settle time after promotion ends (the evidence of the whole fleet).
components[].rollout.settleIntentRef.namestringyesup to 63 charactersName of an Intent in the platform project.
components[].rollout.sloRefobjectThe objective watched during the bake and the settle time.
components[].rollout.sloRef.namestringyesName of the SLO.
components[].rollout.intentRefobjectThe Intent (of the platform project) whose probes are watched during the canary and the settle time: when it was Ready as the canary started and a probe fails afterwards, the release controller rolls the component back itself, without waiting for an objective to burn.
components[].rollout.intentRef.namestringyesName of the Intent.
components[].dependsOnlist of stringup to 16 itemsComponents that must be done first.
components[].routeslist of objectup to 20 itemsThe hostnames and URL patterns that reach this Worker, as desired state (spec 0047 section 3). The controller creates what is missing, repairs what points elsewhere or was deleted by hand, and deletes only what it created itself and the release no longer lists.
components[].routes[].kindstring (one of)yesCustomDomain, RouteCustomDomain: a hostname the Worker serves, with its record and certificate managed for it. Route: a URL pattern in a zone that runs the Worker.
components[].routes[].hostnamestringup to 253 charactersFor a CustomDomain: the hostname, for example inference.etorm.com.
components[].routes[].patternstringup to 253 charactersFor a Route: the URL pattern, for example api.etorm.com/*.
components[].routes[].zoneIdstringyeslength 1 to 64The zone the hostname or pattern belongs to.

Status

FieldTypeRequiredDefaultAllowedDescription
phasestring (one of)Inactive, GatesPending, GateFailed, Rolling, Ready, RolledBack, FrozenWhere the release stands.
observedGenerationintegerThe generation of the spec this status describes.
gateslist of objectThe state of each required check.
gates[].namestringThe check.
gates[].statestringsuccess, failure, pending or missing.
gatesWaivedobjectPresent while a person's GateWaiver approval lets this release through gates that are not green (spec 0047 section 14): who, why, which approval and which gates were not green.
gatesWaived.bystringWho approved the waiver.
gatesWaived.reasonstringWhy.
gatesWaived.approvalstringThe Approval object.
gatesWaived.gateslist of stringThe gates that were not green, with their state.
componentslist of objectPer component: desired, running, phase.
components[].namestringThe component.
components[].desiredstringDesired version id.
components[].runningstringThe version that has all the traffic, or empty while a canary splits it.
components[].previousstringThe version that ran before this rollout (what a rollback returns to).
components[].phasestring (one of)Pending, Blocked, Canary, Done, RolledBackWhere the component stands.
components[].sinceintegerUnix time of the last phase change.
components[].canarySinceintegerUnix time the canary started.
components[].healthyAtStartbooleanWhether the component's Intent was Ready as its canary started (a probe that fails afterwards is then blamed on the deploy).
components[].redeployedAtintegerUnix time of the last redeploy (RedeployComponent) of this component.
components[].settleUntilintegerUntil when a burning objective still rolls the component back.
components[].settleCheckedbooleanThe fleet's evidence (rollout.settleIntentRef) was checked when the settle time ended.
components[].loopBlockedbooleanThe component promoted and drifted twice for this version (another controller puts the old version back): it stays Blocked, an Incident says so, and the release goes on without it.
components[].messagestringWhy it is waiting or failed, in a sentence.
components[].uploadedobjectThe version this controller uploaded from the component's bundle.
components[].uploaded.digeststringThe digest of the bundle.
components[].uploaded.versionIdstringThe version it became.
components[].uploaded.cronslist of stringThe cron triggers the bundle declared.
components[].uploaded.schedulesErrorstringWhy the cron triggers could not be set (tried again every pass).
components[].routeslist of objectThe routes this controller created or adopted for the component: what it may change or delete.
components[].routes[].keystringdomain:<hostname> or route:<pattern>@<zone>.
components[].routes[].idstringThe provider's identifier.
historylist of objectThe last 100 transitions: component, from, to, outcome, who decided.
history[].atintegerUnix time.
history[].componentstringThe component.
history[].fromstringThe version before.
history[].tostringThe version after.
history[].outcomestringcanary, promoted, rolled-back, drift, deployed, failed.
history[].bystringWho or what decided.
conditionslist of objectReady, Progressing, Degraded and Drifted (spec 0047 sections 2 and 3).
conditions[].typestringCondition type.
conditions[].statusstringTrue, False or Unknown.
conditions[].reasonstringA word from the reason registry.
conditions[].messagestringA sentence.

Columns in listings

ColumnFrom
Commit.spec.commit
Active.spec.active
Phase.status.phase
Ready.status.conditions[?(@.type=='Ready')].status

All resources