Volumes

Update a volume's configuration using the details provided in the request body.

put/v1/apps/{app_name}/volumes/{volume_id}

Request

  • Base URL
    https://api.machines.dev
  • Auth
    HTTP bearer

Path parameters

app_namestring required

Fly App Name

volume_idstring required

Volume ID

Request body

auto_backup_enabledboolean

Take daily automatic snapshots of the volume. Unchanged if omitted.

snapshot_retentioninteger

Number of days to keep snapshots of the volume, from 1 to 60. Unchanged if omitted.

Response

OK

attached_alloc_idstring

Always null.

Deprecated: volumes are no longer attached to Nomad allocations.

attached_machine_idstring

ID of the Machine the volume is attached to, or null if it is not attached.

auto_backup_enabledboolean

Whether daily automatic snapshots are taken.

block_sizeinteger

Size of a filesystem block, in bytes. See blocks.

blocksinteger

Size of the volume's filesystem, in blocks of block_size bytes, as last reported by a Machine that mounted the volume. 0 if never reported, if the host could not be reached, or with summary=true.

blocks_availinteger

Number of filesystem blocks available to unprivileged users. See blocks.

blocks_freeinteger

Number of free filesystem blocks, including blocks reserved for the root user. See blocks.

bytes_totalinteger

Size of the volume, in bytes. 0 if the host could not be reached or with summary=true.

bytes_usedinteger

Bytes of storage the volume occupies on its host. Volumes are thinly provisioned, so this grows as blocks are written and does not shrink when files are deleted. It is not the filesystem's usage; use blocks and blocks_free for that. 0 if the host could not be reached or with summary=true.

created_atstring

When the volume was created.

encryptedboolean

Whether the volume is encrypted at rest.

fstypestring

Filesystem the volume was formatted with: ext4, or raw for an unformatted block device.

host_featuresstring[]

Features of the volume's host. Only returned when the request sets the fly-include-host-features: true header.

host_status'ok' | 'unknown' | 'unreachable'

Whether Fly.io could reach the volume's host: ok if it could, unreachable or unknown if it could not, in which case host-reported fields are missing.

idstring

Unique ID of the volume, such as vol_1234567890abcdef.

namestring

Name of the volume. Several volumes of an app can share a name.

regionstring

Code of the region the volume is in.

required_host_featuresstring[]

Host features the volume's host was required to have; see compute.required_host_features in the create request.

size_gbinteger

Size of the volume, in GiB.

snapshot_retentioninteger

Number of days snapshots of the volume are kept.

statestring

State of the volume, such as creating, created, extending, restoring, hydrating, scheduling_destroy, pending_destroy, destroying, destroyed, or failed.

type'local' | 'cache'

Kind of volume: local for regular volumes, or cache for volumes that hold disposable data and support neither snapshots nor restores.

zonestring

Identifies the host the volume is on. Volumes with different zones are on different hosts.

Changes

    • breaking

      the response's property type changed from string to object for status

    • info

      added to the response property allOf list for the response status

    • info

      removed the insufficient_capacity enum value from the response property for the response status

    • info

      removed the name_taken enum value from the response property for the response status

    • info

      removed the unknown enum value from the response property for the response status

    • info

      removed the volume_placement_capacity enum value from the response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status