Host snapshots
cua.env.v1 HostSnapshotsService: the checkpoints a host holds, and copying them between your machines.
Checkpoints a host holds and copying them to your other machines: a manifest of files by SHA-256, read grants, resumable LAN copies with verification, and a fallback copy in S3 or a shared folder. The host's cua-spacesd forwards each call to its cua daemon.
Source: libs/cua/proto/cua/env/v1/snapshots.proto.
HostSnapshotsService#
cua.env.v1.HostSnapshotsService
Snapshots a host holds, and copying them between your machines.
A snapshot here is a local checkpoint (cua.daemon.v1.Checkpoint): a
sandbox's saved memory and disk that forks start from. Checkpoints are
kept on the machine that took them. To fork one on another machine of
the pool, that machine first gets a copy:
- The machine that has it describes it as a manifest: every file (the
memory stream, the RAM file, the disk layers and their backing chain,
UEFI variables, the guest token) by SHA-256 and size. The manifest's
own SHA-256 is the snapshot's digest. It grants read access to those
files for a short time (
ExportHostSnapshot). - The machine that needs it fetches each file it does not have yet,
straight from that machine over the LAN (HTTP range requests, so a
transfer that stopped resumes where it stopped), checks every file's
SHA-256, and only then makes it a checkpoint of its own
(
PullHostSnapshot). Files are kept by content, so files that several snapshots share (a base disk) are copied once. - When that machine cannot be reached, the files come from a copy
published to your S3 bucket or Cua Volume (
PublishHostSnapshot).
A checkpoint of a Space that a host provides is taken on that host
(CreateHostSnapshot), where the Space runs, and stays there: forks of
it start there, or on another machine after a copy. DeleteHostSnapshot
deletes one the host holds.
A host serves this service to the same callers as HostSpacesService
(the owner, its editors, and the env token holder of a direct host),
through its cua-spacesd, which forwards each call to the host's cua
daemon.
HostSnapshotsService.ListHostSnapshots#
/cua.env.v1.HostSnapshotsService/ListHostSnapshots, unary: ListHostSnapshotsRequest to ListHostSnapshotsResponse.
The snapshots this host holds.
HostSnapshotsService.ExportHostSnapshot#
/cua.env.v1.HostSnapshotsService/ExportHostSnapshot, unary: ExportHostSnapshotRequest to ExportHostSnapshotResponse.
Describes a snapshot (hashing its files the first time) and grants read access to its files for a limited time.
HostSnapshotsService.PullHostSnapshot#
/cua.env.v1.HostSnapshotsService/PullHostSnapshot, server stream: PullHostSnapshotRequest to PullHostSnapshotResponse.
Copies a snapshot to this host from another host (or the fallback), streaming progress, and adds it as a checkpoint once every file is verified. A snapshot this host already holds with the same digest is not copied again.
HostSnapshotsService.PublishHostSnapshot#
/cua.env.v1.HostSnapshotsService/PublishHostSnapshot, server stream: PublishHostSnapshotRequest to PublishHostSnapshotResponse.
Uploads a snapshot this host holds to the fallback store (S3 or Cua Volume), streaming progress. Files already there are not uploaded again.
HostSnapshotsService.CreateHostSnapshot#
/cua.env.v1.HostSnapshotsService/CreateHostSnapshot, unary: CreateHostSnapshotRequest to CreateHostSnapshotResponse.
Checkpoints a Space this host provides (CheckpointSandbox on the
host): it keeps running. The owner checkpoints any; another account
only the Spaces it created. Fails with NOT_FOUND when the host does
not provide that Space, and INVALID_ARGUMENT when the name is taken.
HostSnapshotsService.DeleteHostSnapshot#
/cua.env.v1.HostSnapshotsService/DeleteHostSnapshot, unary: DeleteHostSnapshotRequest to DeleteHostSnapshotResponse.
Deletes a checkpoint this host holds (forks made from it keep
running). The owner deletes any; another account only the ones it
took here. A pinned checkpoint is refused until it is unpinned.
Fails with NOT_FOUND when the host does not hold it.
Types in cua/env/v1/snapshots.proto#
HostSnapshot#
A snapshot a host holds.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The checkpoint's name. |
digest | 2 | string | SHA-256 of its manifest (hex), or empty when it was never exported. |
abi | 3 | string | Which machines can restore it: <engine>/<accelerator>/<arch>, for example qemu/hvf/aarch64. A snapshot forks only on a host whose HostNodeStatus.snapshot_abis lists its ABI. |
size_bytes | 4 | uint64 | Bytes of all its files, when known. |
source | 5 | string | The sandbox it was taken from (its name on the machine that took it). |
created_at_ms | 6 | int64 | When it was taken (Unix milliseconds; 0 when unknown). |
pinned | 7 | bool | Pinned: kept until it is unpinned. |
shared_memory | 8 | bool | Its forks share its RAM copy-on-write (a QEMU memory checkpoint). |
runtime_type | 9 | string | The engine that holds it (qemu, firecracker, gvisor, ...). |
image | 10 | string | The image of the sandbox it was taken from. |
SnapshotFallback#
Where hosts fetch a snapshot when the machine that has it cannot be reached: a copy in your S3 bucket, or in a folder every host mounts (your Cua Volume, a NAS share).
| Field | # | Type | Description |
|---|---|---|---|
s3 | 1 | SnapshotS3 | An S3 bucket (or an S3-compatible endpoint). Credentials are the host's own (the AWS default chain on that host). |
dir | 2 | string | A folder every host mounts, for example your Cua Volume (~/Cua Volume/snapshots); a leading ~ is each host's home. Empty with s3 unset: no fallback. |
SnapshotS3#
An S3 location for snapshot files.
| Field | # | Type | Description |
|---|---|---|---|
bucket | 1 | string | The bucket. |
prefix | 2 | string | Key prefix, for example cua-snapshots/. |
region | 3 | string | Region (empty: the host's default). |
endpoint | 4 | string | Endpoint of an S3-compatible service (empty: AWS). |
SnapshotSource#
A host to fetch snapshot files from.
| Field | # | Type | Description |
|---|---|---|---|
url | 1 | string | Base URL of the host's snapshot files, for example http://192.168.1.20:3211/v1/snapshots. |
grant | 2 | string | The read grant ExportHostSnapshot returned. |
name | 3 | string | The host's name, for progress reports. |
ListHostSnapshotsRequest#
Request for HostSnapshotsService.ListHostSnapshots.
No fields.
ListHostSnapshotsResponse#
Response for HostSnapshotsService.ListHostSnapshots.
| Field | # | Type | Description |
|---|---|---|---|
snapshots | 1 | repeated HostSnapshot | The snapshots, by name. |
abis | 2 | repeated string | The snapshot ABIs this host can restore. |
ExportHostSnapshotRequest#
Request for HostSnapshotsService.ExportHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The checkpoint's name. |
grant_ttl_secs | 2 | uint32 | How long the read grant lasts, in seconds (0: 3600; at most 86400). |
ExportHostSnapshotResponse#
Response for HostSnapshotsService.ExportHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
snapshot | 1 | HostSnapshot | The snapshot. |
manifest | 2 | bytes | The manifest (JSON). It holds the checkpoint's record, guest token included: pass it only to your own machines. |
grant | 3 | string | A grant to read the snapshot's files from this host, until it expires. |
path | 4 | string | Path of this host's snapshot files under its cua-spacesd address (/v1/snapshots), for SnapshotSource.url. |
urls | 5 | repeated string | Base URLs this host serves the files on, as it knows its own addresses (its direct listener; each LAN address when it listens on all), for SnapshotSource.url. Empty: the host serves none (it is not set up with --direct); use the fallback. |
PullHostSnapshotRequest#
Request for HostSnapshotsService.PullHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
manifest | 1 | bytes | The manifest from ExportHostSnapshot. Empty: read it from the fallback by name. |
sources | 2 | repeated SnapshotSource | Hosts that have the files, tried in order. |
fallback | 3 | SnapshotFallback | Where to fetch files no source could give. |
name | 4 | string | The snapshot's name, when manifest is empty. |
PublishHostSnapshotRequest#
Request for HostSnapshotsService.PublishHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The checkpoint's name. |
fallback | 2 | SnapshotFallback | Where to publish it (required). |
SnapshotSyncProgress#
Progress of a snapshot copy.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The snapshot's name. |
digest | 2 | string | Its digest. |
from | 3 | string | Where the files come from now: a host's name, s3 or volume (or, when publishing, where they go). |
bytes_done | 4 | uint64 | Bytes copied so far. |
bytes_total | 5 | uint64 | Bytes to copy in all (files already here are not counted). |
bytes_reused | 6 | uint64 | Bytes not copied because this host had those files already. |
done | 7 | bool | The last message: the copy is finished. |
verified | 8 | bool | Every file's SHA-256 matched the manifest. |
PullHostSnapshotResponse#
Response for HostSnapshotsService.PullHostSnapshot: one progress report.
| Field | # | Type | Description |
|---|---|---|---|
progress | 1 | SnapshotSyncProgress | The copy's progress. |
PublishHostSnapshotResponse#
Response for HostSnapshotsService.PublishHostSnapshot: one progress
report.
| Field | # | Type | Description |
|---|---|---|---|
progress | 1 | SnapshotSyncProgress | The upload's progress. |
CreateHostSnapshotRequest#
Request for HostSnapshotsService.CreateHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
space | 1 | string | The Space: its relay machine (relay:<machine> or the bare id), or its local:<name> on the host (a direct Space). |
name | 2 | string | The checkpoint's name (unique among the host's checkpoints and sandboxes). |
pin | 3 | bool | Pin the new checkpoint. |
CreateHostSnapshotResponse#
Response for HostSnapshotsService.CreateHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
snapshot | 1 | HostSnapshot | The new checkpoint. |
DeleteHostSnapshotRequest#
Request for HostSnapshotsService.DeleteHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | The checkpoint's name. |
DeleteHostSnapshotResponse#
Response for HostSnapshotsService.DeleteHostSnapshot.
| Field | # | Type | Description |
|---|---|---|---|
message | 1 | string | What happened, for people. |