0004. Init time SLO: a fitness function caps how long nereus init takes¶
Status: Proposed (2026-10-18)
Intent¶
nereus init brings the platform up, and how long it takes is a quality the project measures and guards (#141): an SLO (service level objective) of 8 minutes on the local k3d undercloud, and 20 minutes on a cloud (Azure first) once the AKS overcloud (#92) and the pivot (#61) exist. A fitness function fails CI when init misses its time objective by more than a tolerance, naming the slowest steps; the progress of #88 colours the clock by the share of the time objective used, so a person sees the drift long before CI fails.
Every value is a setting with a default in code. The values a person changes live in one object of the platform's API group in the nereus namespace, so the pivot (#61) moves them to the overcloud with the rest of the platform's state, as Cluster API's clusterctl move moves objects, and nothing is reconfigured by hand.
Provisional. The word (SLO), the kind (ServiceLevelObjective), the config group and the shape of the object are chosen for the initial configuration and the tests of this slice. They are expected to change with use: when more objectives arrive (per-step objectives, the first login of docs/inception.md, the measurements of #102), a new spec revisits them.
The scene that ends the slice¶
nereus init --yes # the total ends with the SLO: "slo 8m, 3% green"
nereus config slo show
# SETTING VALUE SOURCE
# local 8m default
# ...
nereus config slo set --local 4m --tolerance 5
nereus config slo show # local and tolerance now come from the cluster
nereus config slo reset # back to the defaults in code
nereus init --yes --check-slo # what test/scene and CI run: fails above the SLO + tolerance
The object¶
One ServiceLevelObjective object (short name slo), named default, in the nereus namespace (names.NAMESPACE), of the platform's API group (names.API_GROUP, v1alpha1); its CRD is cli/src/nereus/crds/servicelevelobjective.yaml, applied by init with the other kinds.
| Field | Type | Default (constant in cli/src/nereus/slo.py) |
Meaning |
|---|---|---|---|
spec.targets.local |
duration | 8m (LOCAL) |
The time objective of init on the local target (k3d), from the start of its steps to the end of the last one. |
spec.targets.cloud |
duration | 20m (CLOUD) |
The time objective on a cloud (Azure first), from init's start until the overcloud is up and has taken over after the pivot. Keyed by the cloud reef, never by a Nereid's name (#313). Recorded, not enforced, until #92 and #61. |
spec.bands.yellow |
percent | 50 (YELLOW) |
From this share of the time objective, the clock is yellow. |
spec.bands.orange |
percent | 75 (ORANGE) |
From this share, orange, and the slowest step so far is shown. |
spec.bands.red |
percent | 100 (RED) |
Above this share, red: the objective is missed, and init still finishes. |
spec.tolerance |
percent | 20 (TOLERANCE) |
The fitness function fails above the time objective plus this share of it (120% by default). |
- A duration is minutes and seconds,
5m,4m30sor90s(pattern^([0-9]+m)?([0-9]+s)?$, validated withre.fullmatchby the CLI and by the CRD), never zero. - The bands must rise:
yellow < orange <= red. The CLI refuses a set that breaks the order. - Spec only. The CLI writes
spec(ADR 0005); there is no Nereid and nostatus.init's timings are printed, not stored: a run's history is #102's. - Only the fields set are written. A field the object leaves out falls back to its default in code, so a change of a default reaches every cluster that did not choose its own value.
Precedence¶
Each value, on its own: the object's field, else the default in code. nereus config slo show prints each value with its source (cluster or default), as init prints its settings.
The first init. The cluster, and so the object, does not exist when init starts. init starts with the defaults, and reads the object in its kinds and namespace step, once the kinds are applied in the cluster it is preparing; from that step on, the bands and the check use what it read. On a cluster created by that same run, there is no object yet, so the defaults hold for the whole run; on a cluster reused, the object read in the last step decides the total and the check. init never writes the object, and the settings file of init (settings.py) does not carry these values: one place for each value, the cluster, with the defaults in code.
After the pivot (#61). The object moves to the overcloud with the rest of the platform's objects, and the CLI reads it there.
The command¶
nereus config is a new group for the platform's own settings kept in the cluster; system stays for reefs and Nereids (ADR 0011). nereus config slo:
show: the six values, each with its source.set --local <duration> --cloud <duration> --yellow <percent> --orange <percent> --red <percent> --tolerance <percent>: writes the options given, keeps the fields already set, and prints the values asshowdoes. At least one option.reset: deletes the object; every value falls back to its default.
The bands in the progress¶
The share is the time since init's steps started over the time objective of its target.
| Band | Share of the time objective | On a terminal (the card of #88) | Anywhere else (plain lines) |
|---|---|---|---|
| green | under yellow |
the clock next to the objective, 18.7s of ~8m expected |
nothing on the step lines |
| yellow | yellow to orange |
the clock in yellow | slo 54% yellow on the line of the step that crossed into it |
| orange | orange to red |
the clock in orange, and the slowest step so far | slo 82% orange on the line that crossed |
| red | over red |
the clock in red, and the slowest step so far | slo 104% red on the line that crossed |
The plain total line ends with the time objective and the band reached: total 18.7s slo 8m, 3% green. The share is rounded down, so 99% is never shown red.
The fitness function¶
nereus init --check-slo runs init as usual, then compares its total with the time objective plus the tolerance. Above it, init fails (exit code 1) after the cluster is ready and the config saved, with the total, the limit and the three slowest steps:
✗ init took 9m41s, over its time objective of 8m plus the 20% tolerance (9m36s); slowest steps: cluster nereus-scn-main-a3f9c2 9m12s, kinds and namespace 21.3s, registry localhost:5111 7.1s; shorten them, or raise the objective: nereus config slo set --local 10m
Between the objective and the limit, it warns and passes, with the same slowest steps and the same suggestion (#857). Without --check-slo, every init on the local target warns past the objective and exits 0, since the cluster is ready by then. The scenes that install the profile pass --check-slo too. test/scene runs init with --check-slo, so the scene job of CI fails when the local objective is missed. The check lives in the CLI, not in the script: the scene does not parse durations, and the output a person reads in the walkthrough stays the same. A CI runner is slower than a laptop: if the first runs show a steady gap, it is recorded on #141 rather than loosening the objective silently.
The cloud target is recorded (the default CLOUD and the field spec.targets.cloud), not enforced: init has no target on a cloud yet. When #92 and #61 add it, init maps that target to cloud as it maps k3d to local, and the same check applies.
The former key (#313). Before #313 the cloud target was keyed spec.targets.azure, the name of a Nereid, which the CLI never names (ADR 0002, ADR 0011). For one release the CRD keeps that field, so the API server does not prune it: the CLI reads any key of spec.targets that is no target's own as cloud when cloud is not set, config slo show warns with the command that moves it (nereus config slo set --cloud <duration>), and any config slo set writes it at cloud and drops the former key. The release after removes the field from the CRD.
Security and quality attributes¶
Under the lens of #28, this slice is alpha.
- Performance, as a fitness function: the time of
initis checked on every pull request, against a value in code that a one-line PR changes with its reason. - What a person sets is validated before it reaches the cluster (durations with
re.fullmatch, percents in range, bands in order), and again by the CRD's schema. - Fitness functions of the slice: unit tests of the bands, the plain and live output, the check and the command; the CRD contract tests;
test/sceneend to end, with--check-slo. - What beta would need: per-step objectives from the median of earlier runs (#141), and the history of runs (#102).
Learn more¶
- Service level objectives (Chris Jones, John Wilkes and Niall Murphy, with Cody Smith, "Service Level Objectives", in Google's Site Reliability Engineering book; sre.google): a target value for a measured quality; here, the time of
init. - Fitness functions come from Building Evolutionary Architectures (Neal Ford, Rebecca Parsons, Patrick Kua, O'Reilly, 2017; evolutionaryarchitecture.com): an automated check that a quality of the architecture holds, run on every change.
init --check-slois one. - Cluster API's
clusterctl move(cluster-api.sigs.k8s.io): the pivot of the objects from the undercloud to the overcloud.