Resources / Invariant
Invariant
A property of the platform stated as a read-only openCypher query over the graph of API objects: the query returns the violating objects, and zero rows means the invariant holds (spec 0047 section 6.5). The platform evaluates it when a kind it reads changes and every 30 minutes, within a row and work budget.
Overview
| API | platform.etorm.com/v1alpha1 |
| Resource | invariants (cluster-scoped inside its cluster) |
| Short names | inv |
| Available in | the platform and project clusters |
| Status | written by a controller through /status |
Minimal example
apiVersion: platform.etorm.com/v1alpha1
kind: Invariant
metadata:
name: example
spec:
query: "<query>"
reads:
- kind: "<kind>"
group: "<group>"
plural: "<plural>"
Spec
| Field | Type | Required | Default | Allowed | Description |
|---|---|---|---|---|---|
query | string | yes | length 1 to 4096 | Read-only openCypher. It returns one row per violating object with the columns cluster, kind and name, and optionally reason. The parameter $now (Unix seconds) is always available. | |
reads | list of object | yes | up to 16 items | The kinds the query reads: every node label in the query must be listed. A change to one of them evaluates the invariant, and a violating row names its kind through this list. | |
reads[].kind | string | yes | The kind, as the label in the query: PublicEndpoint. | ||
reads[].group | string | yes | Its API group: edge.etorm.com. | ||
reads[].plural | string | yes | Its plural resource name: publicendpoints. | ||
parameters | object (free-form) | Further query parameters (values only). | |||
severity | string (one of) | "warning" | info, warning, critical | How urgent a violation is: the severity of the incident. | |
rowBudget | integer | 100 | 1 to 1000 | The most rows the query may return. | |
workBudget | integer | 100000 | 1000 to 1000000 | The most store reads the query may make (the engine has no clock, so reads measure time). | |
incident | boolean | true | Open one Incident while the invariant is violated. |
Status
| Field | Type | Required | Default | Allowed | Description |
|---|---|---|---|---|---|
violationCount | integer | How many rows the last evaluation returned. | |||
violations | list of object | up to 20 items | The first twenty violating objects, sorted: names only. | ||
violations[].cluster | string | Its cluster. | |||
violations[].kind | string | Its kind. | |||
violations[].group | string | Its API group. | |||
violations[].plural | string | Its plural resource name. | |||
violations[].name | string | Its name. | |||
violations[].reason | string | up to 200 characters | Why, when the query says. | ||
observedGeneration | integer | The generation of the spec last evaluated. | |||
conditions | list of object | Holds (no violation) and Ready (the query is valid and within budget). | |||
conditions[].type | string | Condition type. | |||
conditions[].status | string | True, False or Unknown. | |||
conditions[].reason | string | Machine-readable reason. | |||
conditions[].message | string | Human-readable detail. |
Columns in listings
| Column | From |
|---|---|
| Severity | .spec.severity |
| Violations | .status.violationCount |
| Holds | .status.conditions[?(@.type=="Holds")].status |
| Detail | .status.conditions[0].message |