Architecture Decision Records
ADR 0031: The Image Catalog Carries No Launch Configuration; All Deployments Use the Same Launch Semantics
On this page
Date: 2026-10-01 · Status: Accepted (supersedes the parts of ADR 0022 concerning existing deployments retaining image defaults and the launch_contract marker, as well as the remaining image-source-based command mode defaults in ADR 0013)
Based on: Deployment Launch Configuration Consolidation Plan.
Context
ADR 0022 stops new deployments from reading the editable defaults layer in the image catalog (Image Defaults: env, Docker arguments, mounts, model mount path,
entrypoint, cmd, and command mode). To preserve the launch semantics of deployments created before the upgrade, however, it retains this layer and a launch_contract marker:
existing deployments without the marker still launch using the image catalog's current values.
This leaves parallel semantics used only for existing deployments and continues to mislead:
- For each instance, the deployment details page shows a comparison table of the deployment-time snapshot versus current image defaults. New deployment snapshots contain only the fixed baseline, but the comparison uses the current image catalog row as the reference. Any value in that row triggers a "changed" indication and a suggestion that you can synchronize on rebuild—even though rebuilding does not synchronize them.
- The defaults layer for every image version in the built-in seed contains only
HF_HUB_OFFLINE=1, duplicating exactly what all three engines inject themselves. - When empty, the
entrypoint_display,cmd_display,env, andextra_mountscolumns are backfilled from node inspect results, mixing image facts and manual configuration in the same columns without a way to distinguish their sources. - The product has not been released, so no existing deployments need protection.
Decision
- The image catalog describes only artifacts: reference, retrieval address, engine and framework versions, architecture, vendor, enabled and deprecated status, and compatibility facts (ADR 0019).
Remove the image row's
env,docker_args,extra_mounts,model_mount_path,entrypoint_display,cmd_display,command_mode,run_command, andinspect_syncedcolumns; removerun_specand version-levelcommand_modefrom the manifest. Ignore these keys when importing old manifests and offline packages. - The image's built-in ENTRYPOINT/CMD/ENV are runtime facts, not separate catalog data. The container runtime uses them directly. To view them, inspect the node in real time or read the instance's launch facts (runtime-observed image and container inspect data). Inspect results are no longer written back to the catalog, and node-reported image status includes only the image ID.
- All deployments use the same semantics: launch configuration comes only from the engine, the selected inference template preset, placement results, and inputs for this deployment. Remove
the
launch_contractmarker and all branches based on it. Command mode defaults toengine;image-entryandmanualrequire explicit selection in the deployment. - Deployment customization has just one container overrides layer (
deploy.ContainerOverrides, "Container Overrides" in CONTEXT.md): setting and deleting environment variables, mounts, Docker arguments,/dev/shm, model mount path, entrypoint, command, and command mode.env_unsetremoves keys set by any lower layer (engine, compute network, or template); device and dGPU variables injected on the node are not part of the launch env and are unaffected. - Instances no longer save image defaults snapshots. The resolved launch plan in the instance's desired state is its complete launch configuration.
Consequences
- In databases upgraded to this version, unmarked deployments use the new semantics after rebuilding. Deployments using unofficial images that previously relied on catalog
image-entry/manualor env/mount settings must set them explicitly in the deployment. Check and rebuild pre-release demo environments individually. - To reuse a nonstandard launch setup (a dedicated image, preparation scripts, or specific arguments), put it in a user inference template preset; for one-off settings, use container overrides. The image catalog is no longer a third source.
- The manifest
sha256is calculated from the parsed structure, so removing fields invalidates checksums of old manifests. The built-in seed checksums have been recalculated; published online catalogs and offline packages must be regenerated with the newgpuworks-image-manifest. Old files withoutsha256import as usual, ignoring removed keys. - Image details no longer show "Runtime Defaults". To inspect the image entrypoint before choosing
image-entry, run an inspection from image details against a node holding the image: the result is the OCI configuration read at that moment, displayed without saving. For instances that have run, you can also view launch facts. Old catalog values could already differ from the artifact. - For layer sources and precedence, see Deployment Launch Parameter Sources.
Was this page helpful?