Skip to content

hardware: report per-runtime CPU attributes at worker registration - #2345

Closed
Shrutiya Mohan (shrutiyam-glitch) wants to merge 1 commit into
agent-substrate:mainfrom
shrutiyam-glitch:hi-attr
Closed

Shrutiya Mohan (shrutiyam-glitch) wants to merge 1 commit into
agent-substrate:mainfrom
shrutiyam-glitch:hi-attr

Conversation

@shrutiyam-glitch

Copy link
Copy Markdown
Collaborator

Part of #2246

Workers registered only architecture, which is not enough to tell whether a snapshot's memory image will restore on a candidate worker. Each ateom now probes /proc/cpuinfo at registration and reports the attributes its runtime's restore path depends on:

  • ateom-gvisor: architecture and cpu_features, an FNV-1a hash of the sorted host flags. gVisor restores only when the checkpoint's feature set is a subset of the host's, so equal hashes guarantee that check passes. The host flags are hashed rather than runsc cpu-features because runsc is a per-SandboxConfig asset not present at registration.

  • ateom-microvm: architecture, cpu_vendor and cpu_model. Cloud Hypervisor has no compatibility gate of its own, so vendor and model are the coarse guard against cross-CPU restores. Attributes are declared once in the hardware package; hardware.Profile names the subset each runtime reports and hardware.Probe builds the identity, omitting any key it cannot read. ateom.Report takes the identity from its caller and requires one.

  • Tests pass

  • Appropriate changes to documentation are included in the PR

Davanum Srinivas (dims) pushed a commit to dims/substrate that referenced this pull request Oct 9, 2026
…e#2381)

Fixes agent-substrate#2348 

Restoring a sandboxed actor from a checkpointed snapshot requires strict
compatibility between the worker that created the snapshot and the
worker restoring it — across the sandbox class (`gvisor`, `microvm`),
the host hardware (`architecture`, `cpu_features`), and the sandbox
runtime assets (`gvisor_asset_hash`, microVM kernel/rootfs digests).

- **Unified compatibility identity (`SandboxRuntime` &
`VersionedSandboxCompat`)**:
Combines `sandbox_class`, an informational version `name`, and a
`compat_version` (`schema_version` + `repeated AttributeEntry
attributes`) into a single self-contained message. When an actor is
checkpointed, the control plane can copy the worker's `default_runtime`
directly onto the snapshot, and during warm restore the scheduler can
match the snapshot's `SandboxRuntime` against candidate workers without
inspecting runtime-specific fields.
- **Zero-downtime runtime rollouts (`default_runtime` vs.
`restorable_runtimes`)**:
Workers report both a `default_runtime` (used for cold starts and new
checkpoints) and `restorable_runtimes` (other enabled runtime versions
on the worker that can still warm-restore existing snapshots while a new
default version rolls out).
- **Schema-versioned key-value attributes (`schema_version` +
`AttributeEntry`)**:
`compat_version.schema_version` (`"v1"`) versions the compatibility
attribute schema itself, while `attributes` uses a list-map of
`AttributeEntry` (`+k8s:listType=map`, `+k8s:listMapKey=key`) so
declarative validation enforces required keys, values, and length bounds
on every entry.
#### Scope of This PR vs. Follow-ups
- **In this PR**: Establishes the `SandboxRuntime` /
`VersionedSandboxCompat` proto schema and declarative validation,
updates `internal/hardware` (`ProbeHost` and `Matches`), and wires
end-to-end registration of `default_runtime` (with `sandbox_class` and
host architecture) and `restorable_runtimes` through `ateom`, `atelet`,
`ate-api-server`, and `fake-workersync`.
- **Follow-ups**:
- Enrich `default_runtime` (`name`, `gvisor_asset_hash`) and
`restorable_runtimes` from `SandboxConfig` once `SandboxConfig` moves to
`WorkerPool`.
- Probe CPU feature attributes (`cpu_features`) in
`hardware.ProbeHost()` (agent-substrate#2345 - WIP)
- Stamp `worker.status.default_runtime` onto snapshots at
pause/checkpoint time and filter candidate workers with
`hardware.Matches` during warm-restore scheduling.


- [ ] Tests pass
- [ ] Appropriate changes to documentation are included in the PR
Workers reported only architecture under their default_runtime, which
cannot tell whether a snapshot's guest state will restore on a candidate
worker. Each ateom now probes /proc/cpuinfo at registration and reports
the attributes its sandbox class's restore path depends on:
- ateom-microvm: architecture, cpu_vendor and cpu_model (family/model,
  or implementer and variant/part on arm64). Cloud Hypervisor has no
  compatibility gate of its own, so these are the coarse guard against
  loading vCPU state captured on a different CPU.
- ateom-gvisor: architecture only for now. A cpu_features attribute is
  left as a TODO: it should come from CPUID rather than the kernel's
  flags line, and ateom does not yet know which runsc it runs.

Attributes are declared once in the hardware package. hardware.Profile
names the subset a runtime reports, hardware.ProfileFor maps a sandbox
class to its profile, and hardware.ProbeHost builds the v1
VersionedSandboxCompat, omitting any key the host does not expose. New
keys under schema v1 are rollout-safe: a snapshot matches a worker when
the snapshot's keys are a subset of the worker's, so older snapshots
still restore on updated workers, and newer snapshots cold-boot on
workers that predate the key.
@shrutiyam-glitch

Copy link
Copy Markdown
Collaborator Author

Superseded by #2660

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/gvisor area/microVM area/node area/scheduling kind/feature An enhancement / feature request or implementation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants