Shared Volume checkpoint recovery
Shared Volume checkpoint recovery
Live-RW checkpoints keep the existing filesystem-freeze contract: every writer
attachment must freeze its still-mounted guest filesystem, fence its host export,
and flush before the control plane clones the volume. An unsupported guest
FIFREEZE is a failed checkpoint, not permission to clone an active writer.
The host distinguishes a definite EOPNOTSUPP response from a lost response. The
former writes a durable aborted/noFreeze tombstone; the latter retains the
freezing barrier until an exact cancellation proves recovery. Guest mounts and
writer processes are never replaced by an unmount fallback.
Cancellation uses the original attachment identity, epoch, checkpoint lease and
quiesceOperationId. Its own operation ID becomes durable before any mutation.
It can resume each legacy freeze phase and replay an interrupted resuming
phase. A pre-start cancellation records a no-effect tombstone, preventing the
delayed original quiesce from freezing a released attachment. Repeated completed
resume proves the transport but does not issue another thaw.
Before releasing writes, the host proves the persisted daemon PID/start, scope, socket, device, guest mount and actual export mode. It holds root-recovery admission against the exact root-client generation through thaw. A live guest cannot be made writable while root recovery is active.
Deleted guests use a separate no-write proof. An authorized sandbox.delete
cleanup or retry records the exact checkpoint's guest-deleted evidence only after
the VM is absent from both the agent and a complete process inventory, all
attachment scopes are gone, and the export is absent. This also covers legacy
checkpoint records whose attachment metadata an older agent already removed.
Exact cancellation re-proves those absences and retires the checkpoint without
requiring a writable root client or recreating a guest.
If quiesce never created a barrier, cancellation cannot recover identity from a
deleted attachment's missing metadata. The authorized sandbox.delete handler
therefore durably records its command and sandbox identity after cleanup and a
complete no-VM proof. Cancellation may use that record to create the exact
original quiesce/lease/epoch tombstone, but must still re-prove the current VM,
attachment scopes and export absent. Missing metadata, an absent VM alone, or
an unreadable deletion record never grants this authority. Deletion records live
outside sandbox directories and are retained for delayed command recovery.
Unknown protocols, unreadable inventories, mismatched epochs/leases and uncertain transport remain fenced. A process-inventory permission or I/O error is never proof that a VM died.
Behavioral regression coverage lives in
hosts/host-agent/cmd/host-agent/juicefs_checkpoint_recovery_test.go: every freeze
phase, interrupted resume, cancellation before delivery, unsupported versus
ambiguous ioctl results, stale identities, root recovery, deleted legacy guests,
receipt binding and unreadable process inventory. These tests do not establish
that virtio-fs supports transparent freeze on a particular guest kernel; that
requires the real live-writer acceptance rig.