Skip to content

Commit 7626ea3

Browse files
committed
docs: document the sysext build and its delivery step
Record the design and the delivery contract while they are current. Signed-off-by: Fabian Wiesel <fabian.wiesel@sap.com>
1 parent 6b8b1db commit 7626ea3

2 files changed

Lines changed: 499 additions & 0 deletions

File tree

‎delivery/README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# SCI delivery step
2+
3+
**Scope.** `sci-delivery.sh` is this repository's boot-test vehicle. The local
4+
boot proof runs it in a Garden Linux VM to test delivery reconciliation.
5+
Integration HVs receive manifest-selected raws through virtiofs instead (see
6+
section 8 of `../docs/sysext-virt.md`). It is not a supported consumer agent.
7+
The product is the signed release (see "Published boundary"). A consumer that
8+
reuses the step owns selection, staging persistence, key and anchor
9+
provisioning, and restart timing. Image mode and fetch mode are two ways to
10+
run the test vehicle, not two delivery products. Design and reasons:
11+
`../docs/sysext-virt.md`.
12+
13+
## Pass contract
14+
15+
These inputs are checked in order. Any validation failure exits non-zero and
16+
writes nothing to the host.
17+
18+
1. Environment: `HOST_ROOT` exists; `INTERVAL` is a non-negative integer.
19+
2. Fetch mode, when `FETCH_URL` is set, builds the staging set first.
20+
3. Manifest: `<name> <restart-unit>...` entries; `#` comments and blank lines
21+
are ignored. A line `^[A-Z][A-Z0-9_]*=<value>$` is a directive. Unknown
22+
directives fail closed. `TARGET_BASE=<major>` is required and must be
23+
digits only. Every entry must have a staged `<name>.raw`; every
24+
`*-activation.service` shim must name an entry.
25+
4. Staged-raw integrity: `SHA256SUMS` must carry one standard line per entry
26+
(`<64-hex> <name>.raw`) and every raw named in the manifest must hash to
27+
its line. This runs before the gate and before any deployment.
28+
5. Base gate: read `<HOST_ROOT>/etc/os-release`, take the first dot-separated
29+
component of `IMAGE_VERSION` (fallback `GARDENLINUX_VERSION`), and compare
30+
it with `TARGET_BASE`. A mismatch, a missing field, or an unreadable file
31+
is a loud no-op: no deploy, no tool call, no delete, non-zero exit.
32+
6. Reconcile entries and `REMOVE` tombstones, then activate.
33+
34+
## Environment
35+
36+
| Variable | Meaning |
37+
|---|---|
38+
| `HOST_ROOT` | host root mount (default `/host`) |
39+
| `STAGING_DIR` | staging directory (default `/opt/sci`; fetch default `$FETCH_DIR/staging`) |
40+
| `INTERVAL` | seconds between passes; `0` runs one pass (default 60) |
41+
| `NSENTER` | `1` runs host tools via `nsenter -t 1 -m` (default); `0` runs them directly |
42+
| `FETCH_URL` | base URL of one release; unset selects image mode |
43+
| `FETCH_PUBKEY` | PEM key that verifies `SHA256SUMS.sig` (required in fetch mode) |
44+
| `FETCH_SUMS_DIGEST` | optional pinned sha256 of `SHA256SUMS` (64 lowercase hex) |
45+
| `FETCH_DIR` | writable fetch root (default `/var/lib/sci-sysext`) |
46+
47+
`extensions.manifest` is in `delivery/extensions.manifest`.
48+
49+
## Deploy and activate
50+
51+
A raw that is missing or content-different is copied to
52+
`/var/lib/extensions/<name>.raw`; a staged shim that differs is copied to
53+
`/etc/systemd/system/<name>-activation.service`. Both use `.tmp` and `mv`.
54+
Equal files are not rewritten. When nothing changed and no marker is
55+
pending, no host-mutating command runs.
56+
57+
`REMOVE=<name>` deletes only `<name>.raw`, `<name>-activation.service`, and
58+
its `multi-user.target.wants` symlink, then runs the normal activation flow
59+
and never restarts that extension's units. Removal is idempotent. A name
60+
that is also an entry, a duplicate, or an invalid name fails validation.
61+
Dropping an entry deletes nothing on the host.
62+
63+
When anything changed, one sequence runs:
64+
65+
`systemctl daemon-reload` → `systemd-sysext refresh` → `systemctl reload
66+
dbus.service` → `systemctl restart <units>` for each changed raw →
67+
`systemctl enable <name>-activation.service` for every shim and
68+
`systemctl restart` for changed or new entries.
69+
70+
A failing per-extension unit restart is logged with the extension and units;
71+
the remaining restarts and all shims still run, and the pass exits non-zero.
72+
Only unit restarts are tolerant; the refresh trio and shim enable/restart
73+
are fatal.
74+
75+
Before it deletes a host extension, the step writes
76+
`/var/lib/extensions/.sci-delivery-pending`. When only raw or shim files
77+
change, the step writes the marker after copying, before the activation flow.
78+
The step removes the marker when the flow completes. A pass that starts with
79+
the marker replays the full activation flow even when no file changed; without
80+
the marker there is no replay. In such a pass, an interruption after the copies
81+
and before the marker leaves the new files unactivated, and a later unchanged
82+
pass does not repair it. The marker is not an extension.
83+
84+
## Known limitation
85+
86+
`EXTENSION_RESTART_UNITS=` in extension-release files is inert on Garden
87+
Linux 2150.x (systemd 259 needs >= 262). The manifest carries the restart
88+
lists and must stay in sync with the extensions' metadata.
89+
90+
## Fetch mode
91+
92+
Fetch mode downloads one release and does not trust its staging directory. A
93+
pass downloads and verifies `SHA256SUMS` and `SHA256SUMS.sig`, treats the
94+
verified sums as the complete inventory, downloads only files whose staged
95+
hash differs, proves the full set with `sha256sum -c`, and prunes staging
96+
files the inventory no longer lists. It has no selection: the release
97+
manifest replaces any pre-seeded manifest. Every failure exits non-zero and
98+
writes nothing to the host.
99+
100+
A converged pass downloads only `SHA256SUMS` and `SHA256SUMS.sig`.
101+
`STAGING_DIR` and `FETCH_DIR` must therefore live on storage that outlives the
102+
container. The shipped test image keeps them in the container layer.
103+
104+
## Maintainer entry points
105+
106+
```sh
107+
bash mkosi/build.sh # build all seven raws
108+
bash mkosi/build.sh <image> # build one image
109+
bash delivery/build-image.sh # stage, verify SHA256SUMS, build test image
110+
bash delivery/build-image.sh --stage-only
111+
bash delivery/build-image.sh --from-staging <dir>
112+
bash mkosi/boot-test.sh # local boot proofs
113+
.build/venv-test/bin/python -m pytest extensions/tests/ -q
114+
```
115+
116+
`build-image.sh` writes `SHA256SUMS` as standard `sha256sum` lines over the
117+
staged raws, then verifies it before the docker build. `--from-staging`
118+
verifies the shipped file instead of regenerating it.
119+
120+
The test image carries only `sci-delivery:latest`. It is not published.
121+
`delivery/Containerfile` pins its Debian base by index digest.
122+
123+
## Published boundary
124+
125+
Publishing produces data only: the seven `<name>.raw` files, the four
126+
activation shims, `extensions.manifest`, `verity-run.crt`, `SHA256SUMS`, and
127+
`SHA256SUMS.sig`. The release tag is `<Release>-g<short sha>`. The publish
128+
job removes `sci-delivery.sh`, fails closed if it remains, regenerates the
129+
sums over the data set, and signs them. Without
130+
`SYSEXT_UNHARDENED_SIGNING_KEY` the release steps are skipped and no release
131+
exists.
132+
133+
`sci-delivery.sh` and its image are test-only. The CI pipeline
134+
(`.github/workflows/sysext.yml`) builds, signs, and publishes; it is not a
135+
consumer deployment contract. See `../docs/sysext-virt.md` for the trust
136+
boundary and open responsibilities.

0 commit comments

Comments
 (0)