Volumes - Fly.io

You can use the Volumes resource to create and delete volumes. A Fly Volume is persistent storage for a Fly Machine. Learn more about volumes.

Endpoints

GET/v1/apps//volumes POST/v1/apps//volumes GET/v1/apps//volumes/PUT/v1/apps//volumes/DELETE/v1/apps//volumes/PUT/v1/apps//volumes//extend GET/v1/apps//volumes//snapshots POST/v1/apps//volumes//snapshots

Volume properties

Property	Type	Description
`auto_backup_enabled`	bool	Enable automatic daily snapshots. Default true.
`attached_alloc_id`	string	n/a
`attached_machine_id`	string	The ID of the Machine that’s attached to the volume.
`block_size`	int	The size of each memory block in bytes.
`blocks`	int	The total number of blocks in the volume.
`blocks _avail`	int	The number of blocks available for data in the volume.
`blocks_free`	int	The total number of blocks free for data and root user ops.
`created_at`	string	The date and time the volume was created.
`encrypted`	boolean	Whether the volume is encrypted. Default true.
`fstype`	string	The file system type.
`id`	string	The volume ID.
`name`	string	The volume name.
`region`	string	The region where the volume resides, or the target region for volume create.
`size_gb`	int	The size of the volume in GB.
`snapshot_retention`	int	The number of days to retain snapshots. Defaults to 5 when not set. Min 1, max 60.
`state`	string	The state of the volume.
`zone`	string	The hardware zone on which the volume resides.

List all the volumes in an app

GET /apps/{app_name}/volumes Given the name of a Fly App, get a list of all the volumes that belong to it.

Path parameters

string

required

The name of the Fly App to list volumes for.

GET/v1/apps/{app_name}/volumes

curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes" 

Status: 200 OK - Example response

[
    {
        "id": "vol_9vw681egy1jj5xm4",
        "name": "disk",
        "state": "created",
        "size_gb": 3,
        "region": "yul",
        "zone": "09cd",
        "encrypted": true,
        "attached_machine_id": "908057ef21e487",
        "attached_alloc_id": null,
        "created_at": "2023-09-01T19:47:14.774Z",
        "blocks": 768250,
        "block_size": 4096,
        "blocks_free": 768244,
        "blocks_avail": 730163,
        "fstype": "ext4",
        "snapshot_retention": 5,
        "auto_backup_enabled": true,
        "host_dedication_key": ""
    },
    {
        "id": "vol_q4qeekqzxze29dw4",
        "name": "disk",
        "state": "created",
        "size_gb": 3,
        "region": "iad",
        "zone": "a4df",
        "encrypted": true,
        "attached_machine_id": null,
        "attached_alloc_id": null,
        "created_at": "2024-01-02T21:16:38.996Z",
        "blocks": 751366,
        "block_size": 4096,
        "blocks_free": 751360,
        "blocks_avail": 708148,
        "fstype": "ext4",
        "snapshot_retention": 5,
        "auto_backup_enabled": true,
        "host_dedication_key": ""
    }
]

Create a volume

POST /apps/{app_name}/volumes Create a volume for a specific app according to the configuration provided in the request body.

Path parameters

string

required

The name of the Fly App to create a volume for.

POST/v1/apps/{app_name}/volumes

curl -i -X POST \\
      -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
      "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes" \\
      -d '{
      "name": "my_app_vol",
      "region": "ord",
      "size_gb": 10
    }'

Request body schema

{
  "auto_backup_enabled": true,
  "compute": {
    "cpu_kind": "string",
    "cpus": 0,
    "gpu_kind": "string",
    "gpus": 0,
    "host_dedication_id": "string",
    "kernel_args": ["string"],
    "memory_mb": 0
  },
  "encrypted": true,
  "fstype": "string",
  "machines_only": true,
  "name": "string",
  "region": "string",
  "require_unique_zone": true,
  "size_gb": 0,
  "snapshot_id": "string",
  "snapshot_retention": 0,
  "source_volume_id": "string"
}

Body parameters

bool

Enable automatic daily snapshots. Default true.

object

An optional object defining the compute specifications for the expected Machine size and type that the volume will attach to. Used to place the volume on hardware that can host that Machine.

Show compute properties

string

The CPU kind, shared or performance.

int

The number of CPUs.

string

The GPU kind, for example a100-pcie-40gb.

int

The number of GPUs.

string

The ID of a dedicated host to place the volume on.

string[]

Kernel arguments for the Machine.

int

Memory in MB.

string

The file system type. Default ext4.

boolean

If true, the volume can only be attached to Machines (not Nomad allocations).

boolean

Whether to encrypt the volume. Default true.

string

required

The name for the new volume.

string

The region where the volume will be created. Defaults to the Machine’s region if attached. If not attached, defaults to the app’s primary region.

int

The size of the volume in GB. Default 3.

string

The ID of the volume snapshot to use to create the new volume.

string

The ID of the source volume for the volume fork.

boolean

If true, we will provision this volume on hardware that doesn’t have another volume with the same name on it. The typical pattern is to create as many volumes as you need, all with the same name and require_unique_zone: true. This will keep your app available in case a host goes down. This flag can also cause volume creation to fail, in case we have used up all unique zones, in which case you probably want to set it to false. Default true.

int

The number of days to retain snapshots. Defaults to 5 when not set. Min 1, max 60.

Status: 200 OK - Example response

{
    "id": "vol_340088w293z35lp4",
    "name": "new_1028_vol",
    "state": "created",
    "size_gb": 10,
    "region": "ord",
    "zone": "84d3",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2023-11-27T21:47:06.837Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 5,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}

Get a specific volume

GET /apps/{app_name}/volumes/{volume_id} Retrieve details about a specific volume by its ID within an app.

Path parameters

string

required

The name of the Fly App the volume belongs to.

string

required

The ID of the volume to get.

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

curl -i -X GET \\
         -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
         "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r" 

Status: 200 OK - Example response

{
    "id": "vvol_6r7ye90k98ynwk1r",
    "name": "disk",
    "state": "created",
    "size_gb": 3,
    "region": "yul",
    "zone": "09cd",
    "encrypted": true,
    "attached_machine_id": "6e8297dc244287",
    "attached_alloc_id": null,
    "created_at": "2023-09-01T19:47:14.774Z",
    "blocks": 768250,
    "block_size": 4096,
    "blocks_free": 768244,
    "blocks_avail": 730163,
    "fstype": "ext4",
    "snapshot_retention": 5,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}

Update a volume

PUT /apps/{app_name}/volumes/{volume_id} Update parameters on the volume.

Path parameters

string

required

The name of the Fly App to create a volume for.

string

required

The ID of the volume to get.

Body parameters

bool

Enable automatic daily snapshots. Default true.

int

The number of days to retain snapshots. Defaults to 5 when not set. Min 1, max 60.

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

curl -i -X PUT \\
      -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
      "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r" \\
      -d '{
      "snapshot_retention": 10
    }'

Status: 200 OK - Example response

{
    "id": "vol_340088w293z35lp4",
    "name": "new_1028_vol",
    "state": "created",
    "size_gb": 10,
    "region": "ord",
    "zone": "84d3",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2023-11-27T21:47:06.837Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 10,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}

Delete a volume permanently

DELETE /apps/{app_name}/volumes/{volume_id} Delete a volume. This action cannot be undone. Given the name of a Fly App and the volume ID of a Fly volume, delete the volume.

Path parameters

string

required

The name of the Fly App the volume belongs to.

string

required

The ID of the volume to permanently delete.

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

curl -i -X DELETE \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r" 

Status: 200 OK - Example response

{
    "id": "vol_grnejj355dqdj9kr",
    "name": "new_1028_vol",
    "state": "destroyed",
    "size_gb": 3,
    "region": "yyz",
    "zone": "aeee",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2023-12-07T21:35:57.42Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 0,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}

Extend a volume

PUT /apps/{app_name}/volumes/{volume_id}/extend Given the name of a Fly App and a volume ID, you can make a volume bigger by extending it. You can extend (increase) a volume’s size, but you can’t make a volume smaller.

Path parameters

string

required

The name of the Fly App the volume belongs to.

string

required

The ID of the volume to extend.

Body parameters

integer

required

The size in GB to make the volume.

PUT/v1/apps/{app_name}/volumes/{volume_id}/extend

curl -i -X PUT \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r/extend" \\
    -d '{
    "size_gb": 10,
}'

Status: 200 OK - Example response

{
    "volume": {
        "id": "vol_9vw681egy1jj5xm4",
        "name": "disk",
        "state": "created",
        "size_gb": 10,
        "region": "yul",
        "zone": "09cd",
        "encrypted": true,
        "attached_machine_id": "6e8297dc244287",
        "attached_alloc_id": null,
        "created_at": "2023-09-01T19:47:14.774Z",
        "blocks": 0,
        "block_size": 0,
        "blocks_free": 0,
        "blocks_avail": 0,
        "fstype": "",
        "snapshot_retention": 5,
        "auto_backup_enabled": true,
        "host_dedication_key": ""
    },
    "needs_restart": false
}

If needs_restart is true, then your Machine needs to be restarted to make use of the added space.

Get a list of snapshots for a volume

GET /apps/{app_name}/volumes/{volume_id}/snapshots Given the name of a Fly app and a volume ID, list the available snapshots for that volume.

Path parameters

string

required

The name of the Fly App to list snapshots for.

string

required

The ID of the volume to list snapshots for.

GET/v1/apps/{app_name}/volumes/{volume_id}/snapshots

curl -i -X GET \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r/snapshots" \\

Status: 200 OK - Example response

[
    {
        "id": "vs_4LNvXLLK0P6tk6KgqoexaBw",
        "size": 36007729,
        "digest": "76d64a69199766d1600d46f0fd48ad9c-1",
        "created_at": "2023-12-02T20:59:35+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_3NlZ9NNmpvoSPqG6DO8BkDy",
        "size": 36007729,
        "digest": "e06b15e5467de62c5d505fa57923db93-1",
        "created_at": "2023-12-03T21:00:35+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_Ql8xbllZOYDSDgo2D7NYGj",
        "size": 36007729,
        "digest": "c37d2a590a351fa561fdb1ffd2f53d62-1",
        "created_at": "2023-12-04T21:01:35+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_x4AxX44lmpbcpap7vwX5x8e",
        "size": 36007729,
        "digest": "91fac554e5261d8f4eb6f7b69e88c8f9-1",
        "created_at": "2023-12-05T21:01:55+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_DkV2wkk7av1c9Kmlv79PL4o",
        "size": 36007729,
        "digest": "d78b5ff73a87b2bdfecb4a87c89c312b-1",
        "created_at": "2023-12-06T21:02:55+00:00",
        "retention_days": 5
    },
    {
        "id": "vs_K8z1w88ZBOys22zqKGZ36R",
        "size": 36007729,
        "digest": "95dfe85046c67834566ccff2a29b18ec-1",
        "created_at": "2023-12-07T21:03:25+00:00",
        "retention_days": 10
    }
]

Create a volume from a snapshot

POST /apps/{app_name}/volumes Create a new volume from a snapshot backup.

Path parameters

string

required

The name of the Fly App to create a volume for.

Body parameters

string

required

The name for the new volume.

string

required

The target region. Must be in the same region as the Machine you want to attach it to.

int

The size of the volume in GB. Default 3.

string

The ID of the volume snapshot to use to create the new volume.

POST/v1/apps/{app_name}/volumes

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes" \\
  -d '{
  "name": "my-app-vol",
  "region": "yyz",
  "size_gb": 3,
  "snapshot_id": "vs_evl65mZQ937tQ16xGGDX8BN",
}'

Status: 200 OK - Example response

{
    "id": "vol_6vj0ggxl7zjkm2zr",
    "name": "new_1028_vol",
    "state": "restoring",
    "size_gb": 3,
    "region": "yyz",
    "zone": "75ec",
    "encrypted": true,
    "attached_machine_id": null,
    "attached_alloc_id": null,
    "created_at": "2024-02-23T00:41:02.411Z",
    "blocks": 0,
    "block_size": 0,
    "blocks_free": 0,
    "blocks_avail": 0,
    "fstype": "",
    "snapshot_retention": 5,
    "auto_backup_enabled": true,
    "host_dedication_key": ""
}

If you wait a moment and then get the new volume, the state should be “created”.

Create an on-demand volume snapshot (beta)

POST /apps/{app_name}/volumes/{volume_id}/snapshots Create an on-demand volume snapshot.

Path parameters

string

required

The name of the Fly App to create a snapshot for.

string

required

The ID of the volume to create a snapshot of.

POST/v1/apps/{app_name}/volumes/{volume_id}/snapshots

curl -i -X POST \\
    -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \\
    "${FLY_API_HOSTNAME}/v1/apps/my-app-name/volumes/vol_6r7ye90k98ynwk1r/snapshots"

Status: 200 OK - Example response

{
    "Msg": {
        "backup": {
            "id": "85999",
            "app_id": "1700318",
            "volume_id": "9151365284627104",
            "state": "prepare",
            "type": "BACKUP_TYPE_ON_DEMAND",
            "message": "",
            "created_at": "2024-02-16T19:30:43.914350121Z",
            "updated_at": "2024-02-16T19:30:43.914350121Z",
            "finished_at": null,
            "graph_id": "vs_gwMAXwwLjOVuo7jL96v2kGXU2"
        }
    }
}

Wait a few moments for the snapshot to get created and then get the list of snapshots to confirm.

​Volume properties

​List all the volumes in an app

​Path parameters

​Create a volume

​Path parameters

​Body parameters

​Get a specific volume

​Path parameters

​Update a volume

​Path parameters

​Body parameters

​Delete a volume permanently

​Path parameters

​Extend a volume

​Path parameters

​Body parameters

​Get a list of snapshots for a volume

​Path parameters

​Create a volume from a snapshot

​Path parameters

​Body parameters

​Create an on-demand volume snapshot (beta)

​Path parameters

​Related topics

Volume properties

List all the volumes in an app

Path parameters

Create a volume

Path parameters

Body parameters

Get a specific volume

Path parameters

Update a volume

Path parameters

Body parameters

Delete a volume permanently

Path parameters

Extend a volume

Path parameters

Body parameters

Get a list of snapshots for a volume

Path parameters

Create a volume from a snapshot

Path parameters

Body parameters

Create an on-demand volume snapshot (beta)

Path parameters

Related topics