This example replaces dataset-v1 with dataset-v2 at /datasets/current
while preserving the sandbox, session, guest boot, and independent process.
Register both read-only catalog entries on the owning node and grant the
sandbox’s tenant access to them. Put v1 and v2 in each image’s /version
file. Keep each name bound to the same immutable image while held. Use Cocoon
v0.7.2 or newer and set SANDBOX_ADDR and SANDBOX_API_TOKEN for the client.
A sandbox token alone cannot manage volumes. For a complete sleep and wake sequence,
see the external controller example.
Entries registered at runtime work the same way. The API also supports writable and attach-only entries.
Pause application reads before replacement. Close files, mmap mappings, cwd,
and bind mount references on the old disk. Replacement unmounts the old disk
before mounting the new one, so the path has a short unavailable interval.
The independent process below uses /tmp and can continue running.
import os
from cocoonsandbox import Client
def process_identity(sb, session, pid):
stat = sb.exec("cat", f"/proc/{pid}/stat")
starttime = stat.rsplit(") ", 1)[1].split()[19]
boot = sb.exec("cat", "/proc/sys/kernel/random/boot_id").strip()
return sb.id, session.id, boot, pid, starttime
client = Client(os.environ["SANDBOX_ADDR"], api_token=os.environ["SANDBOX_API_TOKEN"])
v1 = [{"name": "dataset-v1", "mount": "/datasets/current"}]
v2 = [{"name": "dataset-v2", "mount": "/datasets/current"}]
with client.new("rt:24.04", ttl_seconds=900) as sb:
with sb.session(cwd="/tmp", env={"DATASET_SESSION": "same"}) as session:
pid = sb.spawn("sleep", "3600", cwd="/tmp")
try:
identity = process_identity(sb, session, pid)
sb.set_volumes(v1)
assert sb.exec("cat", "/datasets/current/version").strip() == "v1"
sb.patch_volumes(remove=["dataset-v1"], add=v2)
sb.set_volumes(v2)
assert sb.exec("cat", "/datasets/current/version").strip() == "v2"
assert process_identity(sb, session, pid) == identity
assert session.id in sb.sessions()
assert session.exec("printenv", "DATASET_SESSION").strip() == "same"
view = sb.get_volumes()
assert view["volumes_want"] == view["volumes"] == v2
assert view["converging"] is False
sb.set_volumes([])
assert process_identity(sb, session, pid) == identity
finally:
sb.kill(pid)
A successful run reads v1, then v2, and preserves every identity assertion.
The repeated full target is a no-op on a settled mount.
This example starts without other volumes. Retain any volumes you intend to
keep in a full PUT, or use PATCH to replace only the dataset names. All mounted
and attach-only entries support live removal in either mode.
None, a nil Go slice, and a missing volumes field do not
mean an empty target.
Go uses the same owning handle and client API token.
v2 := sandbox.Volume{Name: "dataset-v2", Mount: "/datasets/current"}
_, err := sb.PatchVolumes(ctx, sandbox.VolumePatch{
Remove: []string{"dataset-v1"},
Add: []sandbox.Volume{v2},
})
if err != nil {
return err
}
For a 409 mount conflict, use the guest path in states[].error to close
references or remove unexpected mounts, then retry. For a transport failure or
timeout, GET the current target and confirmed set before retrying the target.
A failed call can already have changed devices. VolumeError retains a
complete failure view in Go’s Response or Python’s .response.
pending or detaching with converging: false needs a caller retry. GET does
not run device repair. After sandboxd restarts with the original VM still
alive, unfinished entries report an interrupted operation and keep their
admission holds. Detailed errors survive only within one daemon lifetime.
If the VMM exits, a sandbox holding volumes is release-only. Release it and
create a new sandbox; neither PUT with an empty target nor daemon restart
restores the original processes.