Skip to content
Hayonix

Concepts

Storage and volumes

Container disk, pod volumes and network volumes: what each is for, what survives a stop or a configuration change, and where volumes live.

Three kinds of storage

KindLivesSurvives
Container disk (container_disk_gb)Inside the containerNothing: it is reset whenever the container is recreated
Pod volume (volume)Mounted in one podStops, restarts, resets and configuration changes; deleted when the pod is terminated, unless you keep it
Network volume (/v1/volumes)On its own, mounted into podsEverything until you delete it

A new volume's top directory is writable by every user (mode 1777, like /tmp), so an image that runs as an unprivileged user can use it at once. It is set only when the volume is created: if you change its owner or mode, that stays. If the mount path already exists in the image with files in it, the container engine copies those files, their owner and the directory's mode into an empty volume the first time it is mounted there.

A configuration change recreates the container

Changing a pod's configuration (image, environment, command, ports, hardware, mounted volumes) replaces its container. Only volume data survives: anything written to the container disk is gone, and running processes are restarted. Stopping and starting a pod also gives it a fresh container. Keep data you need on a volume.

Restart or reset

ActionContainer diskVolumesHost and GPUsIdentity, addresses, settings
POST /v1/pods/{pod_id}/restartkeptkeptkeptkept
POST /v1/pods/{pod_id}/resetfresh (recreated from the image)keptkeptkept

A reset is for a pod whose container disk you want back to the image's state (a broken install, a full disk) without giving up its host, GPUs or volumes. It works on a pod that is on a host (running, or whose main process exited); a stopped pod already starts with a fresh container disk. Billing continues as for a running pod: the old container's time ends when it stops, the new one's starts when it starts. The CLI's pods reset asks before it resets.

Adding or removing an SSH key is the exception: keys reach the machine separately and never recreate a container.

Volumes live on one host

Until shared storage is available, a volume is stored on the machine of the first pod that mounts it, and is then pinned to that host: every pod that mounts it, now or later, runs there, and waits for capacity on that host when it is full. pinned_to_host on a volume shows this.

Network volumes on serverless workers

A serverless endpoint (queue or HTTP) can mount network volumes of its project into every worker: set volumes on the endpoint, each with a mount_path and read_only (default false). Mounts belong to the release, so changing them rolls out a new release like any other change to the worker. Workers and pods that mount the same volume see the same files, which is how a pod can prepare data that jobs then read.

The same rule applies as for pods: a volume lives on one host, so every worker of the endpoint runs on that host and waits for capacity there when it is full, even when other hosts have room. Choose hardware that host has. A worker's claim on a volume ends when the worker ends; a paused worker (fast resume) keeps it.

A volume an endpoint uses cannot be deleted: DELETE /v1/volumes/{volume_id} answers 409 volume_attached while the endpoint's current release mounts it or a worker of an older release still runs. endpoint_attachments on the volume lists those endpoints.

Growing and deleting

Sizes are enforced

A volume holds no more than its size, and a container disk no more than container_disk_gb (sizes are in GiB): a write beyond it fails with a disk-quota error, as on a full disk. The space used is measured on the host while a pod or worker mounts the volume: usage on the volume, used_bytes on each of a pod's volumes and container_disk on the pod, also shown on the pod's Metrics tab and on the Volumes page.

Growing and deleting

Volumes can grow but never shrink. Growing one moves its limit on the host at once, without restarting the containers that use it. Deleting a volume deletes its data at once and stops its billing; a volume that is mounted must be detached first.