From 97a48ad772d2b81bb0eebbbb6c8af4771bc0d0fe Mon Sep 17 00:00:00 2001 From: Andrea Anderson Date: Wed, 27 Sep 2023 19:28:12 -0400 Subject: [PATCH] Re-org of volumes content (#1062) * start volume rework * add landing page and nav and minor edits * test typo * fix typo * fix links * change tip to note * updates and edits * update nav and move index * fixes * update nav and fix some links * capitalization and naming * final changes and revert to old nav --- apps/volume-manage.html.markerb | 161 ++++++++++++++++ apps/volume-storage.html.markerb | 283 ++++++++++++----------------- database-storage-guides.html.md | 2 +- partials/_firecracker_nav.html.erb | 12 +- reference/regions.html.markerb | 2 +- reference/volumes.html.markerb | 201 ++------------------ volumes/index.html.markerb | 34 ++++ 7 files changed, 338 insertions(+), 357 deletions(-) create mode 100644 apps/volume-manage.html.markerb create mode 100644 volumes/index.html.markerb diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb new file mode 100644 index 0000000000..2922d39967 --- /dev/null +++ b/apps/volume-manage.html.markerb @@ -0,0 +1,161 @@ +--- +title: Manage volume storage +layout: docs +nav: firecracker +order: 40 +--- + +Manage Fly Volumes using the [`fly volumes`](/docs/flyctl/volumes/) command. + +
**Note**: `fly volumes` is aliased to `fly volume` and `fly vol`.
+ +## Create a volume + +Run: + +```cmd +fly vol create +``` + +Use the `-r` option to set a [region](/docs/reference/regions/), or select a region when prompted. + +For options, refer to the [`fly volumes create` docs](/docs/flyctl/volumes-create/) or run `fly vol create -h`. + +To add a volume to your app, refer to [Add volume storage](/docs/apps/volume-storage/). + +## Access a volume + +You can access and write to a volume on a Machine just like a regular directory. + +For Machines managed with Fly Launch, the `destination` under `[mounts]` in `fly.toml` is the path for the mounted volumes. + +For Machines managed individually, specify the mount path in the `fly machine clone` command when you [clone a Machine and add a volume](/docs/apps/volume-storage/#add-a-volume-to-a-machine-clone). + +## Extend a volume + +You can extend (increase) a volume's size, but you can't make a volume smaller. + +1. Run `fly volumes list` and copy the volume ID. + +1. Extend the volume size: + + ```cmd + `fly vol extend -s ` + ``` + +1. (Optional) Check the new volume size in the Machine's file system: + + ```cmd + fly ssh console -s -C df + ``` + + Example output: + ```out + ? Select VM: [Use arrows to move, type to filter] + > yyz: 4d891de2f66587 fdaa:0:3b99:a7b:ef:8cc4:dc49:2 withered-shadow-4027 + Connecting to fdaa:0:3b99:a7b:ef:8cc4:dc49:2... complete + Filesystem 1K-blocks Used Available Use% Mounted on + devtmpfs 103068 0 103068 0% /dev + /dev/vda 8191416 172752 7582852 3% / + shm 113224 0 113224 0% /dev/shm + tmpfs 113224 0 113224 0% /sys/fs/cgroup + /dev/vdb 2043856 3072 1930400 1% /storage + ``` + + In the preceding example, the volume is mounted under `/storage` and has been resized to 2GB. The `df` command shows disk space in 1K blocks by default. Use the `-h` flag to return a more human-readable format. + +For options, refer to the [`fly volumes extend` docs](/docs/flyctl/volumes-extend/) or run `fly vol extend -h`. + +## Restore a volume from a snapshot + +We take daily snapshots and keep them for five days. + +1. Run `fly volumes list` and copy the volume ID. + +1. List the volume's snapshots: + + ```cmd + fly vol snapshots + ``` + + Example output: + ```out + Snapshots + ID SIZE CREATED AT + vs_MgLAggLZkYx89fLy 17638389 1 hour ago + vs_1KRgwpDqZ2ll5tx 17649006 1 day ago + vs_nymJyYMwXpjxqTzJ 17677766 2 days ago + vs_R3OPAz5jBqzogF16 17689473 3 days ago + vs_pZlGZvq3gkAlAcaZ 17655830 4 days ago + vs_A9k6age3bQov6twj 17631880 5 days ago + ``` + +1. Restore from the volume snapshot into a new volume of equal or greater size: + + ```cmd + fly volumes create --snapshot-id -s + ``` + + Example output: + ```out + ? Select region: Sydney, Australia (syd) + ID: vol_mjn924o9l3q403lq + Name: pg_data + App: my-app-name + Region: syd + Zone: 180d + Size GB: 3 + Encrypted: true + Created at: 02 Aug 22 21:27 UTC + ``` + +For options, refer to the [`fly volumes snapshots` docs](/docs/flyctl/volumes-snapshots/) or run `fly vol snapshots -h`. + +## Clone a Machine with a volume + +Clone a Machine with a volume to create a new Machine in the same region with an empty volume. Use the `-r` option to clone the Machine into a different [region](/docs/reference/regions/). + +1. Run `fly status` and copy the Machine ID of the Machine to clone. + +1. Clone the Machine: + + ```cmd + fly m clone + ``` + +1. List volumes to check the result: + + ```cmd + fly volumes list + ``` + + Example output showing two volumes with attached Machines: + ```out + 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. +
+ +For options, refer to the [`fly machine clone` docs](/docs/flyctl/machine-clone/) or run `fly m clone -h`. + +## Destroy a volume + +When you destroy a volume, you delete all its data. + +Run: + +```cmd +fly vol destroy +``` + +For options, refer to the [`fly vol destroy` docs](/docs/flyctl/volumes-destroy/) or run `fly vol destroy -h`. + +## Related topics + +- [Fly Volumes overview](/docs/reference/volumes/) +- [Add volume storage](/docs/apps/volume-storage/) +- [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes) \ No newline at end of file diff --git a/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index becd5483b4..8729bb521c 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -1,182 +1,157 @@ --- -title: Add Volume Storage +title: Add volume storage layout: docs nav: firecracker order: 30 --- -<%= partial "/docs/partials/v2_transition_banner" %> - -Volumes are local persistent storage for [Fly Machines](/docs/machines/). Volumes allow an app to save its state—to preserve configuration, session or user data—and then be restarted with that information in place. You can access and write to a volume on a Machine just like a regular directory. - -
-Always run at least two volumes per app. We usually recommend running at least two Machines per app to increase availability, and if you're using volumes, then each Machine should have an attached volume. Also note that volumes don't sync up by themselves; your app needs to take care of that. Refer to [Fly Volumes](/docs/reference/volumes/) for details about how volumes work. -
+Fly Volumes are local persistent storage for [Fly Machines](/docs/machines/). Learn [how Fly Volumes work](/docs/reference/volumes/). ## Launch a new app with a Fly Volume -Launch a new app with one Machine and an attached volume, and then clone the Machine to scale out. +Use [Fly Launch](/docs/apps/) to create a new app with one Machine and an attached volume, and then clone the Machine to scale out. -### Launch the app, but don't deploy it yet +1. Launch a new app from your project source directory, and type `N` at the "deploy now?" prompt: -The app has to exist for the volume to be created. The volume has to exist before you can mount it to a Machine. The shortest path to a Machine with a mounted volume begins by launching the app, and saying `N` to "deploy now?": + ```cmd + fly launch + ``` -```cmd -fly launch -``` -```out -... -Wrote config file fly.toml -? Would you like to deploy now? No -... -Your app is ready! Deploy with `flyctl deploy` -``` + ```out + ... + Wrote config file fly.toml + ? Would you like to deploy now? No + ... + Your app is ready! Deploy with `flyctl deploy` + ``` -### Configure the app to mount the new volume +1. Add a [`[mounts]` section](/docs/reference/configuration/#the-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: -Add a [`[mounts]` section](/docs/reference/configuration/#the-mounts-section) in the app's `fly.toml`. The `fly deploy` command you'll run in the next step will create the Machine and the volume during the deploy process. + ```toml + [mounts] + source="myapp_data" + destination="/data" + ``` -The following example configuration exposes data from a volume named `myapp_data` under the `/data` directory in the Machine's file system: +1. Deploy the app: -```toml -[mounts] - source="myapp_data" - destination="/data" -``` + ```cmd + fly deploy + ``` -### Deploy the app +1. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine). -```cmd -fly deploy -``` +1. (Recommended if your app handles replication) Clone the first Machine to scale out to two Machines with volumes: -On the first deployment, you'll get one Machine. Confirm this with `fly status`: + ```cmd + fly machine clone + ``` -```cmd -fly status -``` + List volumes to check the result: -Example output: -```out -App - Name = myapp - Owner = personal - Hostname = myapp.fly.dev - Image = image:latest - Platform = machines - -Machines -PROCESS ID VERSION REGION STATE CHECKS LAST UPDATED -app 5683606c41098e 1 lhr started 1 total 2023-04-26T20:40:48Z -``` + ```cmd + fly volumes list + ``` -### Confirm the volume is mounted + Example output showing two volumes with attached Machines: + ```out + 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 + ``` -You can check on all the volumes in your app using `fly volumes list`. The `ATTACHED VM` column lets you know which Machine, if any, the volume is mounted on. +
+Warning: `fly machine clone` doesn't write data into the new volume. +
-List the volumes: +## Add volumes to an existing app -```cmd -fly volumes list -``` +Add a volume to an app created with [Fly Launch](/docs/apps/). -Example output: -```out -ID STATE NAME SIZE REGION ZONE ENCRYPTED ATTACHED VM CREATED AT -vol_zmjnv8m81p5rywgx created data 1GB lhr b6a7 true 5683606c41098e 3 minutes ago -``` +1. Add a [`[mounts]` section](/docs/reference/configuration/#the-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: -You can also see the volume in the Machine's file system (there's only one Machine so far). For example: -```cmd -fly ssh console -s -C df -``` -```out -? 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 -``` + ```toml + [mounts] + source="myapp_data" + destination="/data" + ``` -Voilà: our 1GB volume is mounted at `/data`. You can access and write to a volume on a Machine just like a regular directory. +1. Run `fly status` to check the [regions](/docs/reference/regions/) of the Machines and then create the volume in the same regions as your app's Machines. For example: -### Clone the first Machine to scale out to two VMs + ```cmd + fly volumes create -r + ``` -```cmd -fly machine clone 5683606c41098e -``` +1. 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. -Check what that did: +1. Deploy the app: -```cmd -fly volumes list -``` + ```cmd + fly deploy + ``` -Example output: +1. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine). -``` -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 -``` +## Add a volume to an unmanaged Machine -`fly machine clone` creates an additional Machine with the same configuration as the source, and creates and mounts a volume for the new Machine, if the source Machine has one. **`fly machine clone` doesn't write data into the new volume.** +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](/docs/apps/volume-manage/#clone-a-machine-with-a-volume) to get a new Machine with an empty volume. -At this point there are two identically configured Machines on the app, each with a volume of the same size. You take it from here, setting up whatever data replication you need. +1. Create the volume in the same region as your app. For example: -### On a V1 (Nomad) app + ```cmd + fly volumes create -r + ``` -Create an additional volume in a region, then [use `fly scale count`](/docs/apps/legacy-scaling/) to add a VM to use it. +1. Clone one of your app's Machines (with no volume) and attach the volume you just created: -## Add volumes to an existing app + ```cmd + fly machine clone -r --attach-volume : + ``` -You can add a volume, or volumes, to an existing app by adding `[mounts]` to the app's `fly.toml` file and creating the volumes using flyctl. + `destination-mount-path` is the directory where the volume should be mounted on the file system. -### Configure the app to mount the new volume + For example: -Add a [`[mounts]` section](/docs/reference/configuration/#the-mounts-section) in the app's `fly.toml`. The `fly deploy` command you'll run in the next step will create the Machine and the volume during the deploy process. + ```cmd + fly machine clone 148eddeef09789 -r yyz --attach-volume vol_8l524yj0ko347zmp:/data + ``` -The following example configuration exposes data from a volume named `myapp_data` under the `/data` directory in the Machine's file system: +1. Repeat the preceding steps as needed to create more Machines with volumes. -```toml -[mounts] - source="myapp_data" - destination="/data" -``` +1. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine). -### Create the volume +1. (Optional) Destroy the Machine used to create the clone: -Create the volumes in the same [regions](/docs/reference/regions/) as your app's Machines. Run `fly status` to check the regions of the Machines. + ```cmd + fly machine destroy + ``` -For example: +## Confirm the volume is attached to a Machine -```cmd -fly volumes create myapp_data -r lhr -``` +Use flyctl to check the status of volumes and Machines. -
-You need to create as many volumes as you have Machines per process in your app. Apps deployed using the `fly launch` command have two Machines in the `app` process by default. -
+### List the Machines -If you configure [mounts] in `fly.toml` and then run `fly deploy` without first creating enough volumes, then you'll get an error similar to this one: +List Machines to check attached volumes: -```out -Error: Process group 'app' needs volumes with name 'myapp_data' to fulfill mounts defined in fly.toml; -Run fly volume create myapp_data -r REGION for the following regions and counts: lhr=1.` +```cmd +fly machine list ``` -The error indicates that the app needs one more volume in the `lhr` region. +Example output: -### Deploy the app +```out +1 machines have been retrieved from app my-app-name. +View them in the UI here -```cmd -fly deploy +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 ``` -Run `fly volumes list` to verify that your volumes now have `ATTACHED VM` populated: +### List the volumes + +List volumes to check attached Machines: ```cmd fly volumes list @@ -189,60 +164,32 @@ ID STATE NAME SIZE REGION ZONE ENCRYPTED vol_zmjnv8m81p5rywgx created data 1GB lhr b6a7 true 5683606c41098e 3 minutes ago ``` -## Add a volume to a Machine clone - -If you're not using the `fly.toml` with `fly deploy` workflow for some Machines, you can still add a volume by cloning a Machine with no volume and attaching a new volume to it. You can also clone a Machine with a volume already attached, which gives you a new Machine with a new, empty, volume attached. - -### Create the volume - -Create the volume in the [region](/docs/reference/regions/) where you want to clone a Machine: - -```cmd -fly volumes create -r -``` - -### Clone the Machine - -Clone one of your app's Machines (with no volume) and attach the volume you just created - -``` -fly machine clone -r --attach-volume : -``` - -`destination-mount-path` is the directory where the volume should be mounted on the file system. +### SSH into the Machine -For example: +View the volume in the Machine file system: ```cmd -fly machine clone 148eddeef09789 -r yyz --attach-volume vol_8l524yj0ko347zmp:/data -``` - -### Destroy the Machine used to create the clone - -Destroy the Machine: -```cmd -fly machine destroy -``` - -Run `fly volumes list` to verify that the volume you just created has the newly-cloned Machine's ID listed under `ATTACHED VM`. - -```cmd -fly volumes list +fly ssh console -s -C df ``` -Example output: +Example output showing a 1GB volume mounted at `/data`: ```out -ID STATE NAME SIZE REGION ZONE ENCRYPTED ATTACHED VM CREATED AT -vol_8l524yj0ko347zmp created data 1GB lhr b6a7 true 5683606c41098e 3 minutes ago +? 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 ``` -Repeat the process for each machine that you want to add a volume to. - -## Remove a volume from an app - -You can't currently unmount a volume from an existing Machine. If you need to remove volumes from your app, you can [scale it](/docs/apps/scale-count/) down to zero Machines, [destroy all the volumes](/docs/reference/volumes#destroy-a-volume), remove the `mounts` section from `fly.toml`, and redeploy. **Only destroy a volume whose data you no longer need access to.** +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. -### On a V1 (Nomad) app +## Related topics -Remove the `mounts` section from `fly.toml` and redeploy. This will create a new Machine without a volume. [Destroy any unused volumes](/docs/reference/volumes#destroy-a-volume), **only if you no longer need their data**. +- [Fly Volumes overview](/docs/reference/volumes/) +- [Manage volume storage](/docs/apps/volume-manage/) +- [`mounts` section](/docs/reference/configuration/#the-mounts-section) in the `fly.toml` Fly Launch configuration file +- [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes) \ No newline at end of file diff --git a/database-storage-guides.html.md b/database-storage-guides.html.md index 704431ce60..ea143fbcb1 100644 --- a/database-storage-guides.html.md +++ b/database-storage-guides.html.md @@ -19,7 +19,7 @@ Explore these, and further options, for data storage in the following sections. Anything an App VM writes to its root disk is ephemeral: when the VM is redeployed, the root file system is rebuilt using its Docker image, deleting any data written to it since it was started up. This is fine for `/tmp` files, but most apps need to keep state in a database or another form of persistent storage. -- **[Fly Volumes](/docs/reference/volumes/)** - Persistent storage on Fly.io is provided by Fly Volumes. You can use Volumes on an App directly, or run a separate database App with Volume storage and connect an App to that. A Fly Volume is a slice of NVMe disk storage attached to the server that hosts your Machine. Volumes have pros and cons, and you should read up on [Fly Volumes](/docs/reference/volumes/) before deciding whether they're the best solution for your use case. +- **[Fly Volumes](/docs/volumes/)** - Persistent storage on Fly.io is provided by Fly Volumes. You can use Volumes on an App directly, or run a separate database App with Volume storage and connect an App to that. A Fly Volume is a slice of NVMe disk storage attached to the server that hosts your Machine. Volumes have pros and cons, and you should read the [Fly volumes overview](/docs/reference/volumes/) before deciding whether they're the best solution for your use case. ## Fly.io Database Projects diff --git a/partials/_firecracker_nav.html.erb b/partials/_firecracker_nav.html.erb index 70217906c7..68577b6ddb 100644 --- a/partials/_firecracker_nav.html.erb +++ b/partials/_firecracker_nav.html.erb @@ -61,9 +61,6 @@
  • <%= nav_link "Get Information about an App", "/docs/apps/info/" %>
    • -
  • - <%= nav_link "Add Volume Storage", "/docs/apps/volume-storage/" %> -
  • <%= nav_link "Scale Machine CPU and RAM", "/docs/apps/scale-machine/" %>
    • @@ -73,6 +70,12 @@
  • <%= nav_link "Auto Stop and Start Machines", "/docs/apps/autostart-stop/" %>
    • +
  • + <%= nav_link "Add volume storage", "/docs/apps/volume-storage/" %> +
    • +
  • + <%= nav_link "Manage volume storage", "/docs/apps/volume-manage/" %> +
  • <%= nav_link "Restart an App", "/docs/apps/restart/" %>
    • @@ -99,8 +102,7 @@ <%= nav_link "Databases & Storage", "/docs/database-storage-guides/" %>
    • - <%= nav_link "Volumes", "/docs/reference/volumes" %> -
      • + <%= nav_link "Volumes", "/docs/volumes" %>
    • <%= nav_link "Fly Postgres", "/docs/postgres/" %>
      • diff --git a/reference/regions.html.markerb b/reference/regions.html.markerb index cafb538f2b..7da432a6e5 100644 --- a/reference/regions.html.markerb +++ b/reference/regions.html.markerb @@ -63,6 +63,6 @@ You can see the list of Fly.io regions any time with [`fly platform regions`](ht You can see which regions your app is running in with [`fly status`](https://fly.io/docs/flyctl/status/). -[Fly volumes](/docs/reference/volumes/) and [Fly Machines](/docs/machines/) are tied to the region they're created in. +[Fly Volumes](/docs/reference/volumes/) and [Fly Machines](/docs/machines/) are tied to the region they're created in. When an application instance is started, the three-letter name for the region it's running in is stored in the VM's `FLY_REGION` environment variable. This, along with other [Runtime Environment](/docs/reference/runtime-environment/) information, is visible to your app running on that instance. diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index b94a599585..dd477759e8 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -1,18 +1,16 @@ --- -title: Volumes +title: Fly Volumes overview layout: docs -sitemap: false nav: firecracker +order: 20 --- -<%= partial "/docs/partials/v2_transition_banner" %> +Apps can store only ephemeral data on the root file systems of their Machines, because a Machine’s file system gets rebuilt from scratch each time you deploy your app, or when the Machine is restarted. -Apps can store only ephemeral data on the root file systems of their Machines, because a Machine's file system gets rebuilt from scratch each time you deploy your app or the Machine is restarted. Volumes are local persistent storage for [Fly Machines](/docs/machines/). You can use volumes to store your database files, to save your app's state, such as configuration and session or user data, or for any information that needs to persist after deploy or restart. +Fly Volumes are local persistent storage for [Fly Machines](/docs/machines/). You can access and write to a volume on a Machine just like a regular directory. Use volumes to store your database files, to save your app's state, such as configuration and session or user data, or for any information that needs to persist after deploy or restart. A Fly Volume is a slice of an NVMe drive on the physical server your Fly App runs on. It's tied to that hardware. Fly Volumes are a lot like the disk inside your laptop, with the speed and simplicity advantage of being attached to your motherboard and accessible from a mount point in your file system. And the disadvantages that come with being tied to that hardware, too. -If you already know how volumes work, and you're ready to get started, then learn how to [add volume storage for your app](/docs/apps/volume-storage/), step-by-step. - ## Volume considerations * **A volume belongs to one app**: Every Fly Volume belongs to a [Fly App](/docs/reference/apps/) and you can't share a volume between apps. @@ -22,199 +20,38 @@ If you already know how volumes work, and you're ready to get started, then lear * **Create redundancy in your primary region**: If your app needs a volume to function, and the NVMe drive hosting your volume fails, then that instance of your app goes down. There's no way around that. You can run multiple Machines with volumes in your app's primary region to mitigate hardware failures. * **Create and store backups**: If you only have a single copy of your data on a single volume, and that drive fails, then the data is lost. Fly.io takes daily snapshots and retains them for 5 days, but the snapshots shouldn't be your primary backup method. -If volumes don't work for your use case, then you can explore other options for data storage in [Databases & Storage](/docs/database-storage-guides/). +If volumes don't work for your use case, then explore other options for data storage in [Databases & Storage](/docs/database-storage-guides/). -## Volumes and redundancy +## Volume redundancy -
      -Always run at least two volumes per app. We usually recommend running at least two Machines per app to increase availability, and if you're using volumes, then each machine should have an attached volume. If you only have one Machine and volume, you'll have downtime if there's a host or network failure, and whenever you deploy your app. Also remember that volumes don't have built-in replication between them. +
      +Important: Always run at least two volumes per app. We usually recommend running at least two Machines per app to increase availability, and if you're using volumes, then each machine should have an attached volume. If you only have one Machine and volume, then you'll have downtime if there's a host or network failure, and whenever you deploy your app. Also remember that volumes don't have built-in replication between them.
      In a few cases, you can run a single Machine with an attached volume. For example, if you're running an app with a standard SQLite database, or your app is in development and you're not yet worried about downtime. -Many developers use volumes for databases, so if possible, we place each volume you create for your app in a separate hardware zone by default. Note that having each volume in a separate hardware zone limits the number of volumes your app can have in a region. You can configure this setting with the `--require-unique-zone` option when you run [`fly volumes create`](/docs/flyctl/volumes-create/). +Many developers use volumes for databases, so if possible, each volume you create for your app is placed in a separate hardware zone by default. Note that having each volume in a separate hardware zone limits the number of volumes your app can have in a region. You can configure this setting with the `--require-unique-zone` option when you run [`fly volumes create`](/docs/flyctl/volumes-create/). ## Volumes and regions Volumes exist in a single region. For redundancy within a region, you can run multiple Machines with attached volumes by creating multiple volumes with the same name. For example, creating three volumes named `myapp_data` would let up to three instances of the app start up and run. Every volume has a unique ID to allow for multiple volumes with the same name. Remember that volumes don't automatically replicate data between them. -## Using volumes with your Fly App - -Learn more about using volumes: - -- How to [add volume storage for your app](/docs/apps/volume-storage/), step-by-step. -- How to configure the [`mounts` section](/docs/reference/configuration/#the-mounts-section) for volumes in the `fly.toml` Fly Launch configuration file. -- How to [scale an app with volumes attached](/docs/apps/scale-count/#scale-an-app-with-volumes) - -## Reference: Working with volumes using flyctl - -This section is a reference for working with volumes using the [`fly volumes`](/docs/flyctl/volumes/) command. To add a volume to an existing app or launch a new app with a volume refer to [Add Volume Storage](/docs/apps/volume-storage/). - -
      `fly volumes` is aliased to `fly volume` and `fly vol`.
      +## Volume encryption -### Create a volume - -Create a volume for an app using `fly volumes create`. The default volume size is 3GB. The maximum size is 500GB. Refer to [`fly volumes create`](/docs/flyctl/volumes-create/) in the [flyctl reference](/docs/flyctl) for usage and options. - -The following example command creates a new volume named "myapp_data" with 1GB of storage in the yyz (Toronto) [region](/docs/reference/regions/), for the application whose `fly.toml` file is in the working directory. To specify a different app, use the `-a` or `--app` flag. - -```cmd -fly volumes create myapp_data --region yyz --size 1 -``` -```out - ID: vol_kgj54500d3qry2wz - Name: myapp_data - App: myapp - Region: yyz - Zone: acc6 - Size GB: 1 - Encrypted: true -Created at: 04 Mar 23 03:32 UTC -``` - -
      Volumes are, by default, created with encryption-at-rest enabled for additional protection of the data on the volume. Use `--no-encryption` to instead create an unencrypted volume for improved performance at deployment and runtime. -
      -When you create a volume on a Nomad (V1) App, its region is added to the app's region pool to allow app instances to be started with it. +## Volume size -### List volumes +The default volume size is 3GB. The maximum size is 500GB. -Get a list of all the volumes created for an app using `fly volumes list`. Refer to [`fly volumes list`](https://fly.io/docs/flyctl/volumes-list/) in the [flyctl reference](/docs/flyctl) for usage and options. +## Volume snapshots -```cmd -fly volumes list -``` -```out -ID STATE NAME SIZE REGION ZONE ENCRYPTED ATTACHED VM CREATED AT -vol_xme149kke8ovowpl created myapp_data 1GB iad 7806 true 2 minutes ago -vol_od56vjpp95mvny30 created myapp_data 1GB lhr 79f0 true 2 minutes ago -vol_kgj54500d3qry2wz created myapp_data 1GB yyz acc6 true 9 minutes ago -``` +Fly.io takes daily block-level snapshots of volumes. Snapshots are kept for five days. You can restore a volume snapshot into a new volume of equal or greater size. -Use the unique volume ID in commands that reference a specific volume, such as the `show` or `delete` sub-commands. For example, the `fly volumes show` command can display the details for a particular volume: +Snapshots may not have your latest data. You should still implement your own backup plan for important data. -```cmd -fly vol show vol_kgj54500d3qry2wz -``` -```out - ID: vol_kgj54500d3qry2wz - Name: myapp_data - App: myapp - Region: yyz - Zone: acc6 - Size GB: 1 - Encrypted: true -Created at: 04 Mar 23 03:32 UTC -``` - -### Access a volume - -You can access and write to a volume on a Machine just like a regular directory. For Fly Apps, the `destination` under `[mounts]` in `fly.toml` is the path for the mounted volumes. For Machines that are managed separately, you specify the mount path in the `fly machine clone` command when you [clone a Machine and add a volume](/docs/apps/volume-storage/#add-a-volume-to-a-machine-clone). - -### Extend a volume - -Extend a volume using `fly volumes extend`. Volumes can be extended, or made larger, but can't be made smaller. Refer to [`fly volumes extend`](https://fly.io/docs/flyctl/volumes-extend/) in the [flyctl reference](/docs/flyctl) for usage and options. - -To extend a volume, find its ID with `fly volumes list`, then use `fly volumes extend -s `: - -```cmd -fly volumes extend vol_od56vjp5pzmvny30 -s 2 -``` - -where `` is the extended size in GB. - -For most Machines, the attached volume can be extended without a restart. For older Machines, you'll get a message that you need to manually restart the Machine to increase the size of the file system. - -
      -On Nomad (V1) Apps, the instance is automatically restarted. -
      +## Related topics -Get the `id` of the Machine that has the volume mounted (find it under `ATTACHED VM`). - -```cmd -fly volumes list -``` -```out -ID STATE NAME SIZE REGION ZONE ENCRYPTED ATTACHED VM CREATED AT -vol_od56vjp5pzmvny30 created data 2GB yyz acc6 true 4d891de2f66587 36 minutes ago -``` - -If prompted, restart the Machine using `fly machine restart `: - -```cmd -fly machine restart 4d891de2f66587 -``` - -You can check the new volume size in the Machine's file system by running `df` via `fly ssh console`. If there's more than one Machine on the app, `fly ssh console -s` allows you to select the correct one: - -```cmd -fly ssh console -s -C df -``` -```out -? Select VM: [Use arrows to move, type to filter] -> yyz: 4d891de2f66587 fdaa:0:3b99:a7b:ef:8cc4:dc49:2 withered-shadow-4027 -Connecting to fdaa:0:3b99:a7b:ef:8cc4:dc49:2... complete -Filesystem 1K-blocks Used Available Use% Mounted on -devtmpfs 103068 0 103068 0% /dev -/dev/vda 8191416 172752 7582852 3% / -shm 113224 0 113224 0% /dev/shm -tmpfs 113224 0 113224 0% /sys/fs/cgroup -/dev/vdb 2043856 3072 1930400 1% /storage -``` - -Here, the volume is mounted under `/storage` in the Machine's root file system and has been resized to 2GB. The `df` command shows disk space in 1K blocks by default. You can use the `-h` flag to return a more human-readable format. - -### Restore from a snapshot - -List the snapshots that belong to your target volume using the `fly volumes snapshots list` command. We take daily block-level snapshots of volumes and keep them for five days. These snapshots may not have your latest data. You should implement your own backup plan for important data. Refer to [`fly volumes snapshots list`](https://fly.io/docs/flyctl/volumes-snapshots-list/) in the [flyctl reference](/docs/flyctl) for usage and options. - -To list a volume's snapshots, find the volume ID with `fly volumes list`, then use `fly volumes snapshots list `: - -```cmd -fly volumes snapshots list vol_wod56vjyd6pvny30 -``` -```out -Snapshots -ID SIZE CREATED AT -vs_MgLAggLZkYx89fLy 17638389 1 hour ago -vs_1KRgwpDqZ2ll5tx 17649006 1 day ago -vs_nymJyYMwXpjxqTzJ 17677766 2 days ago -vs_R3OPAz5jBqzogF16 17689473 3 days ago -vs_pZlGZvq3gkAlAcaZ 17655830 4 days ago -vs_A9k6age3bQov6twj 17631880 5 days ago -``` - -You can restore a volume snapshot into a volume that's the same size as, or larger than, the source volume, but not into a smaller one. If you don't specify a size with the `-s` flag, then `fly volumes create` requests a 3GB volume. - -To restore from the snapshot to a new volume, use `fly volumes create --snapshot-id -s [-a ]`: - -```cmd -fly volumes create pg_data --snapshot-id vs_0Gvz2kBKJ28Mph4y -a cat-pg -``` -```out -? Select region: Sydney, Australia (syd) - ID: vol_mjn924o9l3q403lq - Name: pg_data - App: cat-pg - Region: syd - Zone: 180d - Size GB: 3 - Encrypted: true -Created at: 02 Aug 22 21:27 UTC -``` - -The `flyctl` output shows the details of the new volume, including its size. - -### Destroy a volume - -Destroy a volume using the `fly volumes destroy` command. Refer to [`fly volumes destroy`](https://fly.io/docs/flyctl/volumes-destroy/) in the [flyctl reference](/docs/flyctl) for usage and options. - -```cmd -fly volumes destroy vol_2n0l9vlnklpr635d -a myapp -``` -```out -Warning! Individual volumes are pinned to individual hosts. You should create two or more volumes per application. Deleting this volume will leave you with 1 volume(s) for this application, and it is not reversible. Learn more at https://fly.io/docs/reference/volumes/ -? Are you sure you want to destroy this volume? Yes -Destroyed volume vol_2n0l9vlnklpr635d from myapp -``` +- [Add volume storage](/docs/apps/volume-storage/) +- [Manage volume storage](/docs/apps/volume-manage/) +- [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes) diff --git a/volumes/index.html.markerb b/volumes/index.html.markerb new file mode 100644 index 0000000000..392e3d519d --- /dev/null +++ b/volumes/index.html.markerb @@ -0,0 +1,34 @@ +--- +title: "Fly Volumes" +layout: docs +nav: firecracker +toc: false +order: 10 +--- + +Fly Volumes are local persistent storage for [Fly Machines](/docs/machines/). + +## Learn + +Understand how volumes work and whether they're right for your use case. + +[Fly Volumes overview](/docs/reference/volumes/) + +## How-Tos + +Get things done with volumes. + +[Add volume storage](/docs/apps/volume-storage/) + +[Manage volume storage](/docs/apps/volume-manage/) + +Related how-tos: + +[Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes) + +## Reference + +Commands and APIs for volumes. + +- [flyctl commands - `fly volumes`](/docs/flyctl/volumes/) +- [Machines API - Volumes](https://docs.machines.dev/swagger/index.html#/Volumes) \ No newline at end of file