[RFC] feature: Carry sysext and confext images in COSI files

[Paco Huelsz (frhuelsz)]

🔍 Description

RFC for carrying sysext and confext images inside COSI. Each entry requires an id matching the DDI's SYSEXT_ID or CONFEXT_ID, reuses ImageFile, and may omit path for Trident-managed placement.

🤔 Rationale

Bundle extensions with the OS and identify updates by (kind, id) rather than by filename or hash.

📝 Checks

• Check dev-docs/manual-validation.md
• git diff --check — passed. No code tests run (RFC only).

📌 Follow-ups

• Decide how bundled images request the placement policy in RFC: slotted extension storage (builds on #789) #838.
• Settle the Runtime Update request and historical rollback policy.

🗒️ Notes

Older Trident versions silently omit bundled extensions; see the RFC's versioning section.

[azure-pipelines]

Azure Pipelines:
1 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Paco Huelsz (frhuelsz)]

Added a section on extension-only updates, and revised the scope accordingly.

The gap was real. select_servicing_type short-circuits: ab_update_required() returns true whenever os.image.sha384 differs, before any subsystem is consulted. The metadata hash covers the extensions section, so with the RFC as originally written, changing only a bundled extension would have forced a full A/B update and a reboot. That made bundling strictly more disruptive than the current Host Configuration route.

An extension-only COSI is the wrong shape. The metadata root requires images, disk with at least one gptRegions entry, bootloader and osPackages, so a COSI without partition images is not representable, and making it so would require those fields to become optional. Every consumer of os.image — filesystem source resolution, derive_host_configuration, ESP detection, verity setup — assumes the image describes a complete OS. The distinction is drawn on content equality instead.

Mechanism. An OS content digest over the parts of the metadata that determine the deployed OS (images[] and disk.gptRegions[] hashes, disk geometry, bootloader, osArch, osRelease), excluding extensions, recorded in the Host Status. Two COSIs with equal digests deploy an identical OS and differ only in their extensions. Trident cannot determine this otherwise: it retains the URL and metadata hash of the applied image, not the metadata, and re-fetching the previous COSI to diff it is not dependable.

The path is requested and then verified, never inferred. It proceeds only when a Runtime Update is explicitly requested, the digests match, and the recorded image is the deployed one. Otherwise Trident refuses with a structured error naming what differs. It must not promote the operation to an A/B update, and must not apply the extension change while leaving other changes unapplied. Refusal is the only acceptable failure, which is what keeps a partially-applied state unreachable.

Rollback is weaker on this path, and that is why it is not automatic. set_up_extensions skips removal of the superseded image only on Clean Install and A/B Update, so a Runtime Update replaces files in the running slot. Rollback re-runs the subsystem with the specs reversed and re-acquires the previous extension image from its source, which for a bundled extension is the previous COSI. A runtime rollback therefore requires the previous COSI to remain reachable; an A/B rollback requires nothing. That trade should be made by the operator, not inferred from a property of two images.

Three questions added to the open list:

• What surface requests an extension-only Runtime Update? There is none today; forceAbUpdate is the nearest precedent.
• What exactly does the OS content digest cover? Excluding too much permits a Runtime Update between images differing in ways Trident does not model; including too much rejects legitimate cases.
• Should the digest be published in the COSI metadata rather than computed? Computing it needs no writer cooperation and cannot be misdeclared, but publishing would let a writer state intent directly.

[Paco Huelsz (frhuelsz)]

Revised, on both points.

Storing the metadata. Replaced the single digest with a structured summary of the deployed image's metadata, recorded in the Host Status: for each entry in images[] and disk.gptRegions[], the image.sha384, uncompressedSize and the entry's identity (partition number, mount point, fsUuid, partType, verity root hash); plus osArch, osRelease, disk geometry and bootloader.

Excluded, with reasons: extensions (the subject of the comparison), osPackages (validated but never acted on), compression.maxWindowLog (governs decompression, and a new extension may legitimately raise it), and id (identifies the file, not its content).

A record rather than a digest, since the digest is derivable from it and the record additionally lets Trident report which partition differs. Not the full metadata, since osPackages is the bulk of it and has no bearing on the decision.

This gives the three outcomes, including the no-op case, which the previous revision missed:

Summary	Extension set	Result
Equal	Equal	No-op.
Equal	Differs	Extension-only change; a Runtime Update suffices.
Differs	Any	A/B update.

os.image.sha384 changes whenever any part of the metadata changes, including id and the ordering of osPackages, so a materially identical image currently forces an A/B update.

The summary carries its own schema version. Where it is absent or of an unrecognised version, Trident falls back to comparing os.image.sha384. That confines a change to ab_update_required() — a core decision — to hosts that have a recorded summary, and gives existing hosts an unchanged upgrade path.

Construction, and the reproducibility problem. This is the more important of the two, and it invalidates the obvious approach. Filesystem UUIDs, inode timestamps, superblock creation and mount times and allocation order all vary between builds, and ZSTD output varies with compression level and library version. Rebuilding from the same source will not generally produce the same images.

So requiring reproducible rebuilds is the wrong approach. The build operation is not "rebuild the image identically with a different extension set", it is "copy an existing COSI, replacing its extension set". Region images and their metadata entries are copied verbatim from the input COSI; no filesystem is rebuilt and no region image is recompressed. Only the extension tar members, the extensions section, compression.maxWindowLog where the new extensions need a larger window, and id change.

Equality is then guaranteed by construction rather than hoped for through reproducibility, and the operation is a tar rewrite rather than an image build. This reframes the writer requirement from a reproducible-builds effort into a bounded COSI-to-COSI rewrite, and it is now listed under Dependencies.

Where a COSI is rebuilt from source instead, its region images differ, the summary differs, and Trident selects an A/B update. That is the safe outcome: the mechanism degrades to current behaviour rather than misclassifying a changed OS as unchanged. The failure mode of an unreproducible build is a redundant A/B update, never a skipped one.

Open questions updated accordingly: the exact coverage of the summary (version is currently excluded), record against digest, and whether the no-op outcome belongs in this RFC at all, given it is a behavioural change independent of extensions.

[Paco Huelsz (frhuelsz)]

Revised over six rounds against the code. Summary of what changed and why.

Design gaps

Problem	Fix
The deployed bundled set had no representation; spec_old holds only what an operator asked for, so Trident could not tell what to remove, detect collisions, or rebuild state when finalize runs separately	Deployed extension inventory in Host Status, current and pending
Pending records promoted at the wrong point for rebooting servicing, which commits only after booting the expected root	Promotion follows the servicing type
ManualRollbackChainItem carries only kind, spec, active volume and install index; even extended, a manual runtime rollback has no payload	Carry inventory and summary; retain payloads for the rollback chain, or refuse
update_host_configuration fails when a processed extension has no matching Host Configuration entry	Source discriminator on effective entries
ExtensionData.sha384 cannot hold both compressed and raw semantics	Compare only within a source

Incorrect claims

• The A/B rollback guarantee was unconditional. validate_extension_images_locations is Host-Configuration-only static validation running before the COSI is read, so bundled destinations are invisible to it. It also does not check read-only, which the RFC had asserted.
• Rejecting verity-backed destinations was wrong: the root-verity /etc overlay is backed by var/lib/trident-overlay on an A/B volume.
• Reading the effective set does not fix SELinux. The check sits in configure(), which returns early for Runtime Updates.
• There is no load-time member-existence check to extend; Cosi::new discovers entries lazily.
• Destination collisions are not fully detectable from metadata, since an omitted path resolves using the name inside the DDI.
• The extension-release warning would have flagged valid extensions; systemd accepts a VERSION_ID mismatch when SYSEXT_LEVEL matches. Narrowed to ID.
• The summary table is the image's requirement, not the outcome; select_servicing_type still maxes across subsystems.
• fsType was missing from the summary and drives resize decisions.
• An old reader's omission does not self-heal, and a no-op returns before persisting Host Status.

Prerequisites found in existing code

• set_up_extensions deletes the newly installed image when an extension keeps its ID and destination but changes content. Pre-existing and reachable today; routine once extensions are bundled.
• Runtime finalize and rollback build their context with image: None, so staged payloads must be durable.
• Staging uses a fixed /var/lib/extensions/.staging with a non-atomic cross-filesystem fallback.

Scope

Disk streaming is out: it would place the files but osconfig returns early on is_stream_image, so the merge units are never enabled. Trident refuses rather than leaving files that never merge. The permitted-directory allow-list is Trident policy, not a property of the format, so it stays out of the schema. Extension-only Runtime Update is now an exit criterion.