From 1fac41440ab2196b2531420899ff14485ad3c1ff Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Fri, 22 Sep 2023 13:55:27 -0400 Subject: [PATCH 01/12] start volume rework --- apps/volume-manage.html.markerb | 131 ++++++++++++++ apps/volume-storage.html.markerb | 283 ++++++++++++------------------- reference/volumes.html.markerb | 197 ++------------------- 3 files changed, 260 insertions(+), 351 deletions(-) create mode 100644 apps/volume-manage.html.markerb diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb new file mode 100644 index 0000000000..fb28cbadb9 --- /dev/null +++ b/apps/volume-manage.html.markerb @@ -0,0 +1,131 @@ +--- +title: Manage volumes +layout: docs +nav: firecracker +order: 30 +--- + +How to manage volumes using the [`fly volumes`](/docs/flyctl/volumes/) command. + +
**Tip**: `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 [`fly vol 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. + +2. Extend the volume size: + + ```cmd + `fly vol extend -s ` + ``` + +3. (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 vol 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. + +2. 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 + ``` + +3. 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 [`fly vol snapshots` docs](/docs/flyctl/volumes-snapshots/) or run `fly vol snapshots -h`. + +## Destroy a volume + +When you destroy a volume, you delete all its data. + +Run: + +```cmd +fly vol destroy +``` + +For options, refer to [`fly vol destroy` docs](/docs/flyctl/volumes-destroy/) or run `fly vol destroy -h`. + +## Related topics + +- [How Fly Volumes work](/docs/reference/volumes/) +- [Add volume storage](/docs/apps/volume-storage/) +- [`mounts` section](/docs/reference/configuration/#the-mounts-section) in `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/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index becd5483b4..a847569101 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -1,182 +1,155 @@ --- -title: Add Volume Storage +title: Add Volume storage layout: docs nav: firecracker -order: 30 +order: 20 --- -<%= 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. -### Launch the app, but don't deploy it yet +1. Launch a new app, 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) 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 -``` +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: -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 -``` - -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 a Machine clone -`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`). -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 +162,30 @@ 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. - -For example: - -```cmd -fly machine clone 148eddeef09789 -r yyz --attach-volume vol_8l524yj0ko347zmp:/data -``` - -### Destroy the Machine used to create the clone +### SSH into the Machine -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`. +View the volume in the Machine file system: ```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.** - -### 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**. +- [How Fly Volumes work](/docs/reference/volumes/) +- [Manage volumes](/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/reference/volumes.html.markerb b/reference/volumes.html.markerb index 0363b4e3ff..4ef366cdc1 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -1,18 +1,14 @@ --- -title: Volumes +title: How Fly Volumes work layout: docs -sitemap: false nav: firecracker +order: 10 --- -<%= 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 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. +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. 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. 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,9 +18,9 @@ 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. @@ -32,189 +28,28 @@ If volumes don't work for your use case, then you can explore other options for 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]() - -## 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`.
- -### 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 -``` +## Volume encryption -
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. - -### List volumes - -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. - -```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 -``` - -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: -```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 -``` +## Volume size -### Access a volume +The default volume size is 3GB. The maximum size is 500GB. -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). +## Volume snapshots -### Extend a volume +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. -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. +Snapshots may not have your latest data. You should still implement your own backup plan for important data. -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 to your app](/docs/apps/volume-storage/) +- [Manage volumes](/docs/apps/volume-manage/) +- [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes) From eb483079ce13ede7a96064a709d33964eda10616 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Fri, 22 Sep 2023 14:15:51 -0400 Subject: [PATCH 02/12] add landing page and nav and minor edits --- apps/volume-index.html.markerb | 31 ++++++++++++++++++++++++++++++ apps/volume-manage.html.markerb | 4 ++-- apps/volume-storage.html.markerb | 2 +- partials/_firecracker_nav.html.erb | 5 ++++- reference/volumes.html.markerb | 4 +++- 5 files changed, 41 insertions(+), 5 deletions(-) create mode 100644 apps/volume-index.html.markerb diff --git a/apps/volume-index.html.markerb b/apps/volume-index.html.markerb new file mode 100644 index 0000000000..244efbb581 --- /dev/null +++ b/apps/volume-index.html.markerb @@ -0,0 +1,31 @@ +--- +title: "Fly Volumes" +layout: docs +toc: false +nav: firecracker +--- + +Volumes are local persistent storage for [Fly Machines](/docs/machines/). + +## Learn + +Get the details and concepts behind volumes. + +[How Fly Volumes work](/docs/reference/volumes/) + +## How-Tos + +Get things done with volumes. + +[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) + +## Reference + +Commands and APIs for volumes. + +- [flyctl `fly volumes` commands](/docs/flyctl/volumes/) +- [Machines API - Volumes](https://docs.machines.dev/swagger/index.html#/Volumes) \ No newline at end of file diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index fb28cbadb9..540b0585e5 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -1,5 +1,5 @@ --- -title: Manage volumes +title: Manage volume storage layout: docs nav: firecracker order: 30 @@ -19,7 +19,7 @@ fly vol create Use the `-r` option to set a [region](/docs/reference/regions/), or select a region when prompted. -For options, refer to [`fly vol create` docs](/docs/flyctl/volumes-create/) or run `fly vol create -h`. +For options, refer to [`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/). diff --git a/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index a847569101..cb98b4f8c6 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -1,5 +1,5 @@ --- -title: Add Volume storage +title: Add volume storage layout: docs nav: firecracker order: 20 diff --git a/partials/_firecracker_nav.html.erb b/partials/_firecracker_nav.html.erb index 70217906c7..2f7d5fe398 100644 --- a/partials/_firecracker_nav.html.erb +++ b/partials/_firecracker_nav.html.erb @@ -64,6 +64,9 @@
  • <%= nav_link "Add Volume Storage", "/docs/apps/volume-storage/" %>
    • +
  • + <%= nav_link "Manage Volume Storage", "/docs/apps/volume-manage/" %> +
  • <%= nav_link "Scale Machine CPU and RAM", "/docs/apps/scale-machine/" %>
    • @@ -99,7 +102,7 @@ <%= nav_link "Databases & Storage", "/docs/database-storage-guides/" %>
    • - <%= nav_link "Volumes", "/docs/reference/volumes" %> + <%= nav_link "Volumes", "/docs/apps/volume-index" %>
    • <%= nav_link "Fly Postgres", "/docs/postgres/" %> diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index 4ef366cdc1..79eec44a5e 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -5,7 +5,9 @@ nav: firecracker order: 10 --- -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. 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. +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. + +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. From e4d387af9fc948ee928de83ab8b0c85b635c2f7f Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Fri, 22 Sep 2023 14:19:38 -0400 Subject: [PATCH 03/12] test typo --- reference/volumes.html.markerb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index 79eec44a5e..49325d11d7 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -5,7 +5,7 @@ nav: firecracker order: 10 --- -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 ephmeral 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. 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. @@ -25,7 +25,7 @@ If volumes don't work for your use case, then explore other options for data sto ## 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. +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. From 668ad034c79ee1e6c95c6781f2d1bfd7e907d7f4 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Fri, 22 Sep 2023 14:30:30 -0400 Subject: [PATCH 04/12] fix typo --- reference/volumes.html.markerb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index 49325d11d7..faf8697f86 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -5,7 +5,7 @@ nav: firecracker order: 10 --- -Apps can store only ephmeral 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 when the Machine is restarted. 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. From 2d25e79b317dcf5c83c17ad48d185e0b9d52bd23 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Fri, 22 Sep 2023 15:03:04 -0400 Subject: [PATCH 05/12] fix links --- apps/volume-storage.html.markerb | 2 +- reference/volumes.html.markerb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index cb98b4f8c6..74fa379c31 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -186,6 +186,6 @@ tmpfs 113224 0 113224 0% /sys/fs/cgroup ## Related topics - [How Fly Volumes work](/docs/reference/volumes/) -- [Manage volumes](/docs/apps/volume-manage/) +- [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/reference/volumes.html.markerb b/reference/volumes.html.markerb index faf8697f86..864b4ed588 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -52,6 +52,6 @@ Snapshots may not have your latest data. You should still implement your own bac ## Related topics -- [Add volume storage to your app](/docs/apps/volume-storage/) -- [Manage volumes](/docs/apps/volume-manage/) +- [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) From 3ab730ffc860fad2277d58fdc65a8c2ce0f3eab3 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Fri, 22 Sep 2023 16:27:52 -0400 Subject: [PATCH 06/12] change tip to note --- apps/volume-manage.html.markerb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index 540b0585e5..fe8a34af79 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -5,9 +5,9 @@ nav: firecracker order: 30 --- -How to manage volumes using the [`fly volumes`](/docs/flyctl/volumes/) command. +How to manage volumes using the [`fly volumes`](/docs/flyctl/volumes/) command. -
      **Tip**: `fly volumes` is aliased to `fly volume` and `fly vol`.
      +
      **Note**: `fly volumes` is aliased to `fly volume` and `fly vol`.
      ## Create a volume From 8ace1512895e800b95654ecd5b1618ea3982a534 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Mon, 25 Sep 2023 10:34:04 -0400 Subject: [PATCH 07/12] updates and edits --- apps/volume-manage.html.markerb | 49 ++++++++++++++++++++++++++------ apps/volume-storage.html.markerb | 10 ++++--- 2 files changed, 46 insertions(+), 13 deletions(-) diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index fe8a34af79..8dd15eb171 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -19,7 +19,7 @@ fly vol create Use the `-r` option to set a [region](/docs/reference/regions/), or select a region when prompted. -For options, refer to [`fly volumes create` docs](/docs/flyctl/volumes-create/) or run `fly vol create -h`. +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/). @@ -37,13 +37,13 @@ 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. -2. Extend the volume size: +1. Extend the volume size: ```cmd `fly vol extend -s ` ``` -3. (Optional) Check the new volume size in the Machine's file system: +1. (Optional) Check the new volume size in the Machine's file system: ```cmd fly ssh console -s -C df @@ -64,7 +64,7 @@ You can extend (increase) a volume's size, but you can't make a volume smaller. 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 vol extend` docs](/docs/flyctl/volumes-extend/) or run `fly vol extend -h`. +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 @@ -72,7 +72,7 @@ We take daily snapshots and keep them for five days. 1. Run `fly volumes list` and copy the volume ID. -2. List the volume's snapshots: +1. List the volume's snapshots: ```cmd fly vol snapshots @@ -90,7 +90,7 @@ We take daily snapshots and keep them for five days. vs_A9k6age3bQov6twj 17631880 5 days ago ``` -3. Restore from the volume snapshot into a new volume of equal or greater size: +1. Restore from the volume snapshot into a new volume of equal or greater size: ```cmd fly volumes create --snapshot-id -s @@ -109,7 +109,38 @@ We take daily snapshots and keep them for five days. Created at: 02 Aug 22 21:27 UTC ``` -For options, refer to [`fly vol snapshots` docs](/docs/flyctl/volumes-snapshots/) or run `fly vol snapshots -h`. +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 @@ -121,11 +152,11 @@ Run: fly vol destroy ``` -For options, refer to [`fly vol destroy` docs](/docs/flyctl/volumes-destroy/) or run `fly vol destroy -h`. +For options, refer to the [`fly vol destroy` docs](/docs/flyctl/volumes-destroy/) or run `fly vol destroy -h`. ## Related topics - [How Fly Volumes work](/docs/reference/volumes/) - [Add volume storage](/docs/apps/volume-storage/) -- [`mounts` section](/docs/reference/configuration/#the-mounts-section) in `fly.toml` Fly Launch configuration file +- [`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/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index 74fa379c31..e9d30f9063 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -60,8 +60,8 @@ Launch a new app with one Machine and an attached volume, and then clone the Mac vol_zmjnv8m81p5rywgx created data 1GB lhr b6a7 true 5683606c41098e 7 minutes ago ``` -
      -Warning
      `fly machine clone` doesn't write data into the new volume. +
      +Warning: `fly machine clone` doesn't write data into the new volume.
      ## Add volumes to an existing app @@ -90,9 +90,9 @@ Launch a new app with one Machine and an attached volume, and then clone the Mac 1. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine). -## Add a volume to a Machine clone +## Add a volume to an unmanaged Machine -For Machines that aren't managed with Fly Launch (`fly.toml` and `fly deploy`). +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. 1. Create the volume in the same region as your app. For example: @@ -183,6 +183,8 @@ 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. + ## Related topics - [How Fly Volumes work](/docs/reference/volumes/) From d5d3b598ba0dbd6d0ed1b6cbe99f572bce778626 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Mon, 25 Sep 2023 17:49:59 -0400 Subject: [PATCH 08/12] update nav and move index --- apps/volume-manage.html.markerb | 7 +++---- apps/volume-storage.html.markerb | 4 ++-- partials/_firecracker_nav.html.erb | 9 +-------- reference/volumes.html.markerb | 6 +++--- .../index.html.markerb | 7 ++++--- 5 files changed, 13 insertions(+), 20 deletions(-) rename apps/volume-index.html.markerb => volumes/index.html.markerb (81%) diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index 8dd15eb171..e003219d75 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -1,8 +1,8 @@ --- title: Manage volume storage -layout: docs +layout: framework_docs nav: firecracker -order: 30 +order: 40 --- How to manage volumes using the [`fly volumes`](/docs/flyctl/volumes/) command. @@ -156,7 +156,6 @@ For options, refer to the [`fly vol destroy` docs](/docs/flyctl/volumes-destroy/ ## Related topics -- [How Fly Volumes work](/docs/reference/volumes/) +- [Volumes overview](/docs/reference/volumes/) - [Add volume storage](/docs/apps/volume-storage/) -- [`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/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index e9d30f9063..ff15ec2765 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -2,7 +2,7 @@ title: Add volume storage layout: docs nav: firecracker -order: 20 +order: 30 --- Fly Volumes are local persistent storage for [Fly Machines](/docs/machines/). Learn [how Fly Volumes work](/docs/reference/volumes/). @@ -187,7 +187,7 @@ The volume is mounted in the directory specified by the `destination` field in t ## Related topics -- [How Fly Volumes work](/docs/reference/volumes/) +- [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/partials/_firecracker_nav.html.erb b/partials/_firecracker_nav.html.erb index 2f7d5fe398..a9b28c5911 100644 --- a/partials/_firecracker_nav.html.erb +++ b/partials/_firecracker_nav.html.erb @@ -61,12 +61,6 @@
    • <%= nav_link "Get Information about an App", "/docs/apps/info/" %>
      • -
    • - <%= nav_link "Add Volume Storage", "/docs/apps/volume-storage/" %> -
      • -
    • - <%= nav_link "Manage Volume Storage", "/docs/apps/volume-manage/" %> -
    • <%= nav_link "Scale Machine CPU and RAM", "/docs/apps/scale-machine/" %>
      • @@ -102,8 +96,7 @@ <%= nav_link "Databases & Storage", "/docs/database-storage-guides/" %>
      • - <%= nav_link "Volumes", "/docs/apps/volume-index" %> -
        • + <%= nav_link "Volumes", "/docs/volumes" %>
      • <%= nav_link "Fly Postgres", "/docs/postgres/" %>
        • diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index 864b4ed588..b3eac582d3 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -1,8 +1,8 @@ --- -title: How Fly Volumes work -layout: docs +title: Volumes overview +layout: framework_docs nav: firecracker -order: 10 +order: 20 --- 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. diff --git a/apps/volume-index.html.markerb b/volumes/index.html.markerb similarity index 81% rename from apps/volume-index.html.markerb rename to volumes/index.html.markerb index 244efbb581..4590f7012a 100644 --- a/apps/volume-index.html.markerb +++ b/volumes/index.html.markerb @@ -1,17 +1,18 @@ --- title: "Fly Volumes" layout: docs -toc: false nav: firecracker +toc: false +order: 10 --- Volumes are local persistent storage for [Fly Machines](/docs/machines/). ## Learn -Get the details and concepts behind volumes. +Understand how volumes work and whether they're right for your use case. -[How Fly Volumes work](/docs/reference/volumes/) +[Volumes overview](/docs/reference/volumes/) ## How-Tos From b205c0ddd56f09244155b21082b61845234c3948 Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Mon, 25 Sep 2023 17:56:29 -0400 Subject: [PATCH 09/12] fixes --- apps/volume-manage.html.markerb | 2 +- partials/_firecracker_nav.html.erb | 6 ++++++ reference/volumes.html.markerb | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index e003219d75..1aeecdedad 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -1,6 +1,6 @@ --- title: Manage volume storage -layout: framework_docs +layout: docs nav: firecracker order: 40 --- diff --git a/partials/_firecracker_nav.html.erb b/partials/_firecracker_nav.html.erb index a9b28c5911..ca8de87c3b 100644 --- a/partials/_firecracker_nav.html.erb +++ b/partials/_firecracker_nav.html.erb @@ -70,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/" %>
        • diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index b3eac582d3..d8cd5eb39b 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -1,6 +1,6 @@ --- title: Volumes overview -layout: framework_docs +layout: docs nav: firecracker order: 20 --- From afb1e4b116381d35461a8ff51fca88a3856fea7c Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Mon, 25 Sep 2023 20:05:24 -0400 Subject: [PATCH 10/12] update nav and fix some links --- apps/volume-manage.html.markerb | 2 +- apps/volume-storage.html.markerb | 2 +- database-storage-guides.html.md | 2 +- partials/_firecracker_nav.html.erb | 4 +-- partials/_volumes_nav.html.erb | 47 ++++++++++++++++++++++++++++++ reference/volumes.html.markerb | 2 +- volumes/index.html.markerb | 6 ++-- 7 files changed, 57 insertions(+), 8 deletions(-) create mode 100644 partials/_volumes_nav.html.erb diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index 1aeecdedad..9371fb05eb 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -1,7 +1,7 @@ --- title: Manage volume storage layout: docs -nav: firecracker +nav: volumes order: 40 --- diff --git a/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index ff15ec2765..d063d134d6 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -1,7 +1,7 @@ --- title: Add volume storage layout: docs -nav: firecracker +nav: volumes order: 30 --- 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 ca8de87c3b..68577b6ddb 100644 --- a/partials/_firecracker_nav.html.erb +++ b/partials/_firecracker_nav.html.erb @@ -71,10 +71,10 @@ <%= nav_link "Auto Stop and Start Machines", "/docs/apps/autostart-stop/" %>
      • - <%= nav_link "Add volume storage", "docs/apps/volume-storage/" %> + <%= nav_link "Add volume storage", "/docs/apps/volume-storage/" %>
      • - <%= nav_link "Manage volume storage", "docs/apps/volume-manage/" %> + <%= nav_link "Manage volume storage", "/docs/apps/volume-manage/" %>
      • <%= nav_link "Restart an App", "/docs/apps/restart/" %> diff --git a/partials/_volumes_nav.html.erb b/partials/_volumes_nav.html.erb new file mode 100644 index 0000000000..05eea1e172 --- /dev/null +++ b/partials/_volumes_nav.html.erb @@ -0,0 +1,47 @@ +
          +
        • + <%= nav_link "Fly Volumes", "/docs/volumes/" %> +
          • +
        +
          +
        • + + Learn + +
            +
          • + <%= nav_link "Volumes overview", "/docs/reference/volumes/" %> +
            • +
          +
          • +
        +
          +
        • + + How-Tos + +
            +
          • + <%= nav_link "Add volume storage", "/docs/apps/volume-storage/" %> +
            • +
          • + <%= nav_link "Manage volume storage", "/docs/apps/volume-manage/" %> +
            • +
          +
          • +
        +
          +
        • + + Reference + +
            +
          • + <%= nav_link "flyctl volumes commands", "/docs/flyctl/volumes/" %> +
            • +
          • + <%= nav_link "Machines API - Volumes", "https://docs.machines.dev/swagger/index.html#/Volumes" %> +
            • +
          +
          • +
        diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index d8cd5eb39b..267549137b 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -1,7 +1,7 @@ --- title: Volumes overview layout: docs -nav: firecracker +nav: volumes order: 20 --- diff --git a/volumes/index.html.markerb b/volumes/index.html.markerb index 4590f7012a..1fab08f890 100644 --- a/volumes/index.html.markerb +++ b/volumes/index.html.markerb @@ -1,7 +1,7 @@ --- title: "Fly Volumes" layout: docs -nav: firecracker +nav: volumes toc: false order: 10 --- @@ -22,11 +22,13 @@ Get things done with volumes. [Manage volume storage](/docs/apps/volume-manage/) +More volume how-tos: + [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes) ## Reference Commands and APIs for volumes. -- [flyctl `fly volumes` commands](/docs/flyctl/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 From af3385e81c25db9617ddd051e866e10a106e12ab Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Tue, 26 Sep 2023 09:59:09 -0400 Subject: [PATCH 11/12] capitalization and naming --- apps/volume-manage.html.markerb | 4 ++-- apps/volume-storage.html.markerb | 2 +- partials/_volumes_nav.html.erb | 2 +- reference/regions.html.markerb | 2 +- reference/volumes.html.markerb | 4 ++-- volumes/index.html.markerb | 4 ++-- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index 9371fb05eb..c3064baf82 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -5,7 +5,7 @@ nav: volumes order: 40 --- -How to manage volumes using the [`fly volumes`](/docs/flyctl/volumes/) command. +Manage Fly Volumes using the [`fly volumes`](/docs/flyctl/volumes/) command.
        **Note**: `fly volumes` is aliased to `fly volume` and `fly vol`.
        @@ -156,6 +156,6 @@ For options, refer to the [`fly vol destroy` docs](/docs/flyctl/volumes-destroy/ ## Related topics -- [Volumes overview](/docs/reference/volumes/) +- [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 d063d134d6..06ae465739 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -187,7 +187,7 @@ The volume is mounted in the directory specified by the `destination` field in t ## Related topics -- [Volumes overview](/docs/reference/volumes/) +- [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/partials/_volumes_nav.html.erb b/partials/_volumes_nav.html.erb index 05eea1e172..942b207ac7 100644 --- a/partials/_volumes_nav.html.erb +++ b/partials/_volumes_nav.html.erb @@ -10,7 +10,7 @@
        • - <%= nav_link "Volumes overview", "/docs/reference/volumes/" %> + <%= nav_link "Fly Volumes overview", "/docs/reference/volumes/" %>
        • 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 267549137b..19dc05b617 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -1,5 +1,5 @@ --- -title: Volumes overview +title: Fly Volumes overview layout: docs nav: volumes order: 20 @@ -7,7 +7,7 @@ order: 20 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. -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. +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. diff --git a/volumes/index.html.markerb b/volumes/index.html.markerb index 1fab08f890..2dc2a70c3c 100644 --- a/volumes/index.html.markerb +++ b/volumes/index.html.markerb @@ -6,13 +6,13 @@ toc: false order: 10 --- -Volumes are local persistent storage for [Fly Machines](/docs/machines/). +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. -[Volumes overview](/docs/reference/volumes/) +[Fly Volumes overview](/docs/reference/volumes/) ## How-Tos From 085002781e38fc362c1d72e0a28cc80c4ce699cd Mon Sep 17 00:00:00 2001 From: andie787 <4andie@gmail.com> Date: Wed, 27 Sep 2023 15:21:16 -0400 Subject: [PATCH 12/12] final changes and revert to old nav --- apps/volume-manage.html.markerb | 4 +-- apps/volume-storage.html.markerb | 10 ++++--- partials/_volumes_nav.html.erb | 47 -------------------------------- reference/volumes.html.markerb | 6 ++-- volumes/index.html.markerb | 4 +-- 5 files changed, 13 insertions(+), 58 deletions(-) delete mode 100644 partials/_volumes_nav.html.erb diff --git a/apps/volume-manage.html.markerb b/apps/volume-manage.html.markerb index c3064baf82..2922d39967 100644 --- a/apps/volume-manage.html.markerb +++ b/apps/volume-manage.html.markerb @@ -1,13 +1,13 @@ --- title: Manage volume storage layout: docs -nav: volumes +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`.
        +
        **Note**: `fly volumes` is aliased to `fly volume` and `fly vol`.
        ## Create a volume diff --git a/apps/volume-storage.html.markerb b/apps/volume-storage.html.markerb index 06ae465739..8729bb521c 100644 --- a/apps/volume-storage.html.markerb +++ b/apps/volume-storage.html.markerb @@ -1,7 +1,7 @@ --- title: Add volume storage layout: docs -nav: volumes +nav: firecracker order: 30 --- @@ -9,9 +9,9 @@ Fly Volumes are local persistent storage for [Fly Machines](/docs/machines/). Le ## 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. -1. Launch a new app, and type `N` at the "deploy now?" prompt: +1. Launch a new app from your project source directory, and type `N` at the "deploy now?" prompt: ```cmd fly launch @@ -41,7 +41,7 @@ Launch a new app with one Machine and an attached volume, and then clone the Mac 1. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine). -1. (Recommended) Clone the first Machine to scale out to two Machines with volumes: +1. (Recommended if your app handles replication) Clone the first Machine to scale out to two Machines with volumes: ```cmd fly machine clone @@ -66,6 +66,8 @@ Launch a new app with one Machine and an attached volume, and then clone the Mac ## Add volumes to an existing app +Add a volume to an app created with [Fly Launch](/docs/apps/). + 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: ```toml diff --git a/partials/_volumes_nav.html.erb b/partials/_volumes_nav.html.erb deleted file mode 100644 index 942b207ac7..0000000000 --- a/partials/_volumes_nav.html.erb +++ /dev/null @@ -1,47 +0,0 @@ -
          -
        • - <%= nav_link "Fly Volumes", "/docs/volumes/" %> -
          • -
        -
          -
        • - - Learn - -
            -
          • - <%= nav_link "Fly Volumes overview", "/docs/reference/volumes/" %> -
            • -
          -
          • -
        -
          -
        • - - How-Tos - -
            -
          • - <%= nav_link "Add volume storage", "/docs/apps/volume-storage/" %> -
            • -
          • - <%= nav_link "Manage volume storage", "/docs/apps/volume-manage/" %> -
            • -
          -
          • -
        -
          -
        • - - Reference - -
            -
          • - <%= nav_link "flyctl volumes commands", "/docs/flyctl/volumes/" %> -
            • -
          • - <%= nav_link "Machines API - Volumes", "https://docs.machines.dev/swagger/index.html#/Volumes" %> -
            • -
          -
          • -
        diff --git a/reference/volumes.html.markerb b/reference/volumes.html.markerb index 19dc05b617..dd477759e8 100644 --- a/reference/volumes.html.markerb +++ b/reference/volumes.html.markerb @@ -1,7 +1,7 @@ --- title: Fly Volumes overview layout: docs -nav: volumes +nav: firecracker order: 20 --- @@ -24,8 +24,8 @@ If volumes don't work for your use case, then explore other options for data sto ## 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, 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. +
        +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. diff --git a/volumes/index.html.markerb b/volumes/index.html.markerb index 2dc2a70c3c..392e3d519d 100644 --- a/volumes/index.html.markerb +++ b/volumes/index.html.markerb @@ -1,7 +1,7 @@ --- title: "Fly Volumes" layout: docs -nav: volumes +nav: firecracker toc: false order: 10 --- @@ -22,7 +22,7 @@ Get things done with volumes. [Manage volume storage](/docs/apps/volume-manage/) -More volume how-tos: +Related how-tos: [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes)