Add volume storage

Fly Volumes are local persistent storage for Fly Machines. Learn how Fly Volumes work.

Launch a new app with a Fly Volume

Use Fly Launch to create a new app with one Machine and an attached volume, and then clone the Machine to scale out.

Launch a new app from your project source directory, specifying --no-deploy so it does not deploy immediately:
```
fly launch --no-deploy
```
After the app is created, add a [mounts] section in the app’s fly.toml, where source is the volume name and destination is the directory where the volume should be mounted on the Machine file system. For example:
```
[mounts]
  source="myapp_data"
  destination="/data"
```

Note: You can’t mount a volume with destination="/" since / is used for the root file system.

Deploy the app:
```
fly deploy 
```
Confirm that the volume is attached to a Machine.

(Recommended if your app handles replication) Clone the first Machine to scale out to two Machines with volumes:

fly machine clone <machine id>

List volumes to check the result:

fly volumes list

Example output showing two volumes with attached Machines:

ID                      STATE   NAME    SIZE    REGION  ZONE    ENCRYPTED       ATTACHED VM     CREATED AT     
vol_ez1nvxkwl3jrmxl7    created data    1GB     lhr     4de2    true            91851edb6ee983  39 seconds ago
vol_zmjnv8m81p5rywgx    created data    1GB     lhr     b6a7    true            5683606c41098e  7 minutes ago

Warning: fly machine clone doesn’t write data into the new volume.

Add volumes to an existing app

Add a volume to an app created with Fly Launch.

Add a [mounts] section in the app’s fly.toml, where source is the volume name and destination is the directory where the volume should be mounted on the Machine file system. For example:
```
[mounts]
  source="myapp_data"
  destination="/data"
```
Run fly status to check the regions of the Machines and then create the volume in the same regions as your app’s Machines. For example:
```
fly volumes create <volume name> -r <region code>
```
Repeat step 2 for each Machine in the process group. If you create an app using the fly launch command, then the app will usually have two Machines in the app process by default.
Deploy the app:
```
fly deploy 
```
Confirm that the volume is attached to a Machine.

Add a volume to an unmanaged Machine

For Machines that aren’t managed with Fly Launch (fly.toml and fly deploy), you can create a volume and attach it when you clone a Machine. You can also clone a Machine with a volume to get a new Machine with an empty volume.

Create the volume in the same region as your app. For example:
```
fly volumes create <volume name> -r <region code>
```
Clone one of your app’s Machines (with no volume) and attach the volume you just created:
```
fly machine clone <machine id> -r <region code> --attach-volume <volume id>:<destination mount path>
```
destination-mount-path is the directory where the volume should be mounted on the file system.

For example:
```
fly machine clone 148eddeef09789 -r yyz --attach-volume vol_8l524yj0ko347zmp:/data
```
Repeat the preceding steps as needed to create more Machines with volumes.
Confirm that the volume is attached to a Machine.
(Optional) Destroy the Machine used to create the clone:
```
fly machine destroy <machine id>
```

Confirm the volume is attached to a Machine

Use flyctl to check the status of volumes and Machines.

List the Machines

List Machines to check attached volumes:

fly machine list

Example output:

1 machines have been retrieved from app my-app-name.
View them in the UI here

my-app-name
ID              NAME        STATE   REGION   IMAGE                  IP ADDRESS                      VOLUME                  CREATED                 LAST UPDATED            APP PLATFORM    PROCESS GROUP   SIZE
328773d3c47d85  my-app-name stopped yul     flyio/myimageex:latest  fdaa:2:45b:a7b:19c:bbd4:95bb:2  vol_6vjywx86ym8mq3xv    2023-08-20T23:09:24Z    2023-08-20T23:16:15Z    v2              app             shared-cpu-1x:256MB

List the volumes

List volumes to check attached Machines:

fly volumes list

Example output:

ID                      STATE   NAME    SIZE    REGION  ZONE    ENCRYPTED       ATTACHED VM     CREATED AT    
vol_zmjnv8m81p5rywgx    created data    1GB     lhr     b6a7    true            5683606c41098e  3 minutes ago

SSH into the Machine

View the volume in the Machine file system:

fly ssh console -s -C df

Example output showing a 1GB volume mounted at /data:

? Select VM: lhr: 5683606c41098e fdaa:0:3b99:a7b:7e:3155:9844:2 nameless-feather-6339
Connecting to fdaa:0:3b99:a7b:7e:3155:9844:2... complete
Filesystem     1K-blocks   Used Available Use% Mounted on
devtmpfs          103068      0    103068   0% /dev
/dev/vda         8191416 172748   7582856   3% /
shm               113224      0    113224   0% /dev/shm
tmpfs             113224      0    113224   0% /sys/fs/cgroup
/dev/vdb         1011672   2564    940500   1% /data

The volume is mounted in the directory specified by the destination field in the [mounts] section of the fly.toml file, or the attach-volume option for cloned Machines.

Fly Volumes overview
Manage volume storage
mounts section in the fly.toml Fly Launch configuration file
Scale an app with volumes

Edit this page on GitHub