Resources / Intent

Intent

What one product of the platform needs to be true, as an ordered list of links (resources that must be Ready and public probes that must pass). The platform computes whether it holds and, when it does not, names the first failing link.

Overview

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

Minimal example

apiVersion: platform.etorm.com/v1alpha1
kind: Intent
metadata:
  name: example
spec:
  product: "<product>"
  requirements:
  - name: "<name>"

Spec

FieldTypeRequiredDefaultAllowedDescription
productstringyesup to 128 charactersThe product in plain words, for example `code.etorm.com serves the Forge web UI`.
evidenceOnlybooleanfalseThe Intent is evidence for a release (its canary or fleet objective), not a product: its links are judged but never repaired and never open an Incident of their own.
sloRefobjectThe objective that measures this product (an SLO of the same cluster).
sloRef.namestringyeslength 1 to 63Name of the SLO.
requirementslist of objectyesup to 32 itemsThe links, in order from the outside in. The first one that is not met is the failing link.
requirements[].namestringyeslength 1 to 63Name of the link, shown in the chain.
requirements[].resourceobjectA resource that must be Ready (condition Ready true, or phase Ready, Running or Active).
requirements[].resource.groupstringyesAPI group of the resource (empty for the core group).
requirements[].resource.versionstringyesAPI version.
requirements[].resource.pluralstringyesPlural resource name.
requirements[].resource.namestringyesObject name.
requirements[].resource.clusterstring"root"Logical cluster of the object (default root).
requirements[].resource.conditionstringup to 63 charactersThe condition that must be True instead of Ready (for example a station's FabricHealthy, spec 0038 section 22); empty: Ready.
requirements[].probeobjectA public URL that must answer as expected, probed from the platform.
requirements[].probe.urlstringyesup to 512 charactersThe address to request with GET.
requirements[].probe.expectCodeinteger200100 to 599The HTTP status the answer must have.
requirements[].probe.expectTextstringup to 256 charactersText the body must contain (empty: any body).
requirements[].probe.gitobjectProbe a real Git fetch of the repository at `url` (the address of the repository, `https://host/<workspace>/<repository>.git`) instead of a GET: list the refs, then fetch `ref` at `depth` and require a pack. `expectCode` and `expectText` do not apply.
requirements[].probe.git.refstring"refs/heads/main"up to 256 charactersThe ref to fetch.
requirements[].probe.git.depthinteger11 to 100How many commits of history to fetch.
requirements[].probe.expectBuildstring (one of)releaseFor a Git probe: the build named in the advertisement (`agent=etorm-git/<build>`) must be the build of the newest Ready release; a Ready release answered by another build fails the link.
requirements[].probe.authstring (one of)platform, probe`platform`: the probe is made with the platform's own credential; `probe`: with the platform probe identity's token (spec 0047 section 2.4). Only to the platform's own names; the host decides.
requirements[].probe.maxSecondsinteger1 to 90The probe is met only if it took no longer than this (a Git probe: default 30; a work probe: default 10).
requirements[].probe.whenReadyobjectA work probe's precondition: an object the probe itself needs (its own endpoint, for example). While it is missing or not Ready the link is shown with cause probe-not-ready and the service is not judged, whatever the order in which the pieces appear.
requirements[].probe.whenReady.groupstringyesAPI group.
requirements[].probe.whenReady.versionstringyesAPI version.
requirements[].probe.whenReady.pluralstringyesPlural resource name.
requirements[].probe.whenReady.clusterstringIts project (default root).
requirements[].probe.whenReady.namestringyesIts name.
requirements[].probe.everySecondsinteger30 to 86400A met work probe runs again at most this often (default 300); a failing one runs every pass.
requirements[].probe.stepslist of objectup to 8 itemsA work probe (spec 0047 section 2.4): the service's real job as ordered requests, each with its expected answer; the first that fails names the link's failure. `{nonce}` (new each run) and `{nowMs}` are replaced in `url` and `body`. `url` above is then only the link's label.
requirements[].probe.steps[].methodstring (one of)"GET"GET, POST, PUT, DELETEThe request method.
requirements[].probe.steps[].urlstringyesup to 512 charactersThe address of the request (a platform name).
requirements[].probe.steps[].bodystringup to 4096 charactersThe request body (never a secret: it is readable in this object).
requirements[].probe.steps[].contentTypestringup to 100 charactersThe body's type (default application/json).
requirements[].probe.steps[].expectCodeinteger200100 to 599The status the answer must have.
requirements[].probe.steps[].expectCodeslist of integerup to 4 itemsAny of these statuses is good (instead of expectCode).
requirements[].probe.steps[].expectTextstringup to 256 charactersText the answer must contain (`{nonce}` allowed).
requirements[].probe.vialist of stringup to 2 itemsThe paths the probe takes: `edge` (the public name, through whatever fronts it: the default) and `origin` (each origin address straight, with the name as SNI and Host). With both, a failure is named by where it is: `edge-to-origin`, `origin-down` or `origin-saturated` (spec 0047 section 2.3).
requirements[].probe.burstinteger0 to 64With `via` origin: open this many parallel connections to each origin that answers and require all of them to be accepted (0: none).
requirements[].probe.endpointRefobjectThe PublicEndpoint whose DNSRecords are the origin addresses (with `via` origin).
requirements[].probe.endpointRef.namestringName of the PublicEndpoint (root cluster).
requirements[].probe.originslist of stringup to 8 itemsOrigin addresses given outright, in addition to those of `endpointRef`.
requirements[].probe.originPortinteger1 to 65535The origin's port (default: the URL's).
requirements[].remediationlist of objectup to 8 itemsThe repair of this link, as an ordered list of bounded actions (spec 0047 section 6, link remediation). While this link is the failing one for two minutes, the first action runs; if the link is not met after its settle time, the next runs. The order of the actions not yet tried follows what has helped this link before. When none is left an incident labelled needs-code is opened.
requirements[].remediation[].actionstring (one of)yesRollbackRelease, RedeployComponent, ResetDurableObject, ApplyDeclared, ReplaceNode, FailoverDNS, RestartPlacement, RerunBootstrapRequest, RotateNow, RederiveListenerTarget, RestartProcess, RaiseFuel, ReplaceGitProcess, RestoreIngressAffinity, RestartLogShipperWhich action (the list is closed, as for a Remediation).
requirements[].remediation[].paramsobject (free-form)Parameters the action's owner defines.
requirements[].remediation[].settleSecondsinteger1200 to 86400How long the link has to become met after the action before the next one runs.
requirements[].remediation[].onCausestringup to 63 charactersFor a probe with several paths: run this step only while the link fails for this cause (`edge-to-origin`, `origin-down`, `origin-saturated`). Empty: for every cause.
requirements[].remediation[].modestring (one of)"apply"apply, planplan only records what would run.
requirements[].remediation[].budgetobjectAt most this many runs of this step in the window.
requirements[].remediation[].budget.maxinteger1at least 1Runs allowed.
requirements[].remediation[].budget.windowSecondsinteger3600at least 60The window.

Status

FieldTypeRequiredDefaultAllowedDescription
phasestringReady when every link is met, Degraded otherwise.
observedGenerationintegerThe generation of the spec this status describes.
failingLinkstringThe name of the first link that is not met (empty when all are); for a probe that knows which path failed, the cause (`edge-to-origin`, `origin-down`, `origin-saturated`).
probableCauselist of objectWhile a link fails: the objects on its dependency path that carry a drift (the name's endpoint, its DNS records, the zone, the zone's settings), the first being the probable cause. `reason` is `proxy-origin-port` when the proxy dials a port the origin's firewall does not open.
probableCause[].groupstringThe cause's API group.
probableCause[].pluralstringThe cause's resource.
probableCause[].namestringThe cause's name.
probableCause[].clusterstringThe cause's cluster.
probableCause[].reasonstringproxy-origin-port, or Drifted.
probableCause[].messagestringWhat differs.
chainlist of objectEvery link with its state, in order.
chain[].namestringName of the link.
chain[].statestring (one of)Met, Unmet, UnknownWhether the link is met.
chain[].detailstringWhy, in one sentence.
chain[].causestring (one of)edge-to-origin, origin-down, origin-saturated, origin-unknown, probe-unauthorized, probe-not-readyFor a probe with several paths: which failure it is (`origin-unknown`: no answer proves the origin up or down from the host that probes). For a work probe: `probe-unauthorized` (the probe could not run as its own identity) or `probe-not-ready` (its precondition whenReady is missing or not Ready): shown here and as the condition Probing, never the failing link. Otherwise it is also `status.failingLink` while this is the first unmet link.
chain[].ranAtintegerA work probe: when it last ran (Unix seconds).
chain[].pathsobject (free-form)What each path of a probe answered: the edge, and per origin address the result and the burst's accepted count.
extensionsobject (free-form)Fields written by other controllers, one entry per controller name. The readiness controller keeps them untouched, and a controller that writes this status must keep what the others wrote (spec 0047 section 2).
conditionslist of objectReady, Progressing and Degraded (spec 0047 section 2).
conditions[].typestringReady, Progressing or Degraded.
conditions[].statusstringTrue, False or Unknown.
conditions[].reasonstringA word from the reason registry.
conditions[].messagestringA sentence.
conditions[].observedGenerationintegerThe generation observed.
conditions[].lastTransitionTimestringWhen the status last changed.
conditions[].remediationobject (free-form)What may be done about it: Wait, Automatic, Incident or None.

Columns in listings

ColumnFrom
Product.spec.product
Ready.status.conditions[?(@.type=='Ready')].status
Failing-Link.status.failingLink
Phase.status.phase

All resources