Shared volumes and backups

這個頁面還沒有翻譯成繁體中文：以下是英文版。

Volumes are the API’s disks underneath Drives (/v1/volumes): a Drive is a volume too, and its id is a vol-…. What only volumes give is the shared volume: a file system that several sandboxes mount at once, each allowed to write or not.

Shared volumes

glac volumes create --name team --shared
glac volumes attach team web:/team
glac volumes attach team worker:/team --read-only
glac volumes detach team worker

With the API: POST /v1/volumes with {"name": "team", "shared": true}, and volumes: [{path, volume, read_only}] when making or changing a sandbox. In Python, glac.volumes.create(name="team", shared=True) and VolumeMount("/team", vol).

• The machine serves a shared volume over NFS to the sandboxes that mount it. They must be on the same machine as the volume (409 not_on_one_machine), except a volume no sandbox has used yet: it moves to the machine of the first sandbox that mounts it, within its region. A machine that does not serve shared volumes answers 503 not_served_here.
• Without size_bytes, a volume may grow to 64 GiB, or to the largest your plan allows if that is less. It takes the space of what is written into it, not its size.
• Detaching a volume that a process in the sandbox is using is refused (409 mount_in_use) unless you add ?force=true. A volume that is attached, or that a snapshot was taken with, cannot be deleted (409 volume_in_use).
• Volumes count with Drives against what a project may keep, and what they hold is billed as what Drives hold: see How Drives work.

For a disk that one sandbox has and that moves between machines, use a Drive.

Backups

A backup is a copy of a volume (a Drive too) at one instant, kept in the object store, sealed with the project’s key. It is not a snapshot of a Drive, which is a version of the Drive: a backup is a copy of its own, a volume is made from it alone, and it outlives the volume. A volume’s backups are incremental: each sends and keeps only the blocks that changed since the backup before it, and points at that one’s for the rest. It stays in the project’s list until it expires or is deleted, and a new volume is made from it whatever became of the volume. One is taken by a call, every day by the volume’s rule, or before a new version of a service that keeps data replaces its instance (its reason: manual, daily, before_version).

glac backups create data --expires-in-days 7    # prints the backup's id
glac backups ls --volume data
glac backups restore bak-0123456789abcdef --name data-back

A backup is making until the object store has all of it, then ready; one that could not be made is failed (failure says why). A volume is made only from a ready one (409 backup_not_ready while it is being made, 409 backup_unusable once it failed). Its consistency says how it was taken: frozen (the file system was still for the copy) or crash (like a disk at the moment the power went). Backups are made only by machines that copy their disks to an object store; elsewhere the call answers 409 not_copied.

A volume made from a backup names it (from_backup) and is restoring until the whole backup is back, then ready; it cannot be mounted before. A machine of the backup’s region that refuses to make it at once (its disk is full, the account has no more room on it, it cannot be reached) is passed over for the next one that copies to the object store, and the volume’s placement_refusals lists those that refused, in the order they were asked, each with the code it refused with (null where the first one asked made it). Where every one refuses, the call answers 503 no_capacity, with the same list. Where the machine it was placed on cannot bring it back, the control plane makes it once more, under the same id, on another machine of the backup’s region: its restore_attempt is 2 then, and first_failure says why the first try failed. If the second fails too, the volume is failed for good, and can only be deleted.

The SDKs, the command line and the MCP server have calls for all of this: see Python, TypeScript, Go, Rust, Java, the command line and the MCP server.

What it costs. A block several backups of a volume need is kept once, and billed once, on the earliest of them; when that one is deleted, on the next. So a backup’s stored_bytes is what it is billed for: the bytes the object store holds (compressed) that it needs and no earlier backup of its volume needs. Its own_bytes is what deleting it would save, what no other backup of its volume needs, and shared_bytes what it needs that others need too. A backup is billed from the moment it is ready until it is deleted or expires, at the price of what sleeping sandboxes keep ($0.02 a GB-month), booked every minute. A backup that is still being made, or that failed, costs nothing. GET /v1/billing says how much of that meter was backups (backups_gb_hours, on its line of state), and GET /v1/usage reports them for any range: kind=backup (glac usage --kind backup), group_by=backup (each backup a group of its own, by its backup_id) and backup_id=bak-… (one backup, whatever became of its volume). What backups keep cannot be stopped by a spend limit or an empty balance: it goes on being counted until they expire or are deleted. An account that owes can still list its backups and make a volume from one, to get its data back; it cannot take new backups.