|
| 1 | +--- |
| 2 | +title: Cache disks |
| 3 | +description: "Give a Fly Machine fast local scratch storage with a cache disk: what it keeps, when it's wiped, performance, limits, and setup with fly.toml, flyctl, or the Machines API." |
| 4 | +--- |
| 5 | + |
| 6 | +A cache disk is local disk space attached to a single Fly Machine, for data your app can rebuild if it's lost. Think build caches, downloaded model weights, package caches, or temporary files that are too large for the Machine's root file system. |
| 7 | + |
| 8 | +Fly.io makes a best effort to keep a cache disk's contents across Machine stops, restarts, and updates, but there's no guarantee. Your app should expect to start with an empty cache disk at any time. If you need the data back, store it on a [Fly Volume](/volumes/overview) or in [object storage](/tigris) instead. |
| 9 | + |
| 10 | +## Cache disks, volumes, and the root file system |
| 11 | + |
| 12 | +| | Root file system | Cache disk | Fly Volume | |
| 13 | +| --- | --- | --- | --- | |
| 14 | +| Survives stop and restart | No | Usually, not guaranteed | Yes | |
| 15 | +| Survives [Machine migration](/reference/machine-migration) | No | No | Yes, the volume is forked to the new host | |
| 16 | +| Survives Machine destroy | No | No | Yes, until you delete the volume | |
| 17 | +| Snapshots and forks | No | No | Yes | |
| 18 | +| Created and managed | With the Machine | In the Machine config | Separately, with `fly volumes` | |
| 19 | +| Max size | Depends on image | 50 GiB | 500GB | |
| 20 | + |
| 21 | +{/* TODO: add a billing row once pricing is set. */} |
| 22 | + |
| 23 | +## What happens to the data |
| 24 | + |
| 25 | +A cache disk belongs to its Machine. It's created when you create or update a Machine with a cache disk config, and it lives on the same host as the Machine. |
| 26 | + |
| 27 | +| Event | Cache disk contents | |
| 28 | +| --- | --- | |
| 29 | +| Machine stops, starts, or restarts on the same host | Usually kept | |
| 30 | +| Machine update that doesn't change the cache disk's size | Usually kept | |
| 31 | +| Cache disk `path` changed | Kept | |
| 32 | +| Cache disk size changed | Wiped. The disk is destroyed and a new empty one is created | |
| 33 | +| [Machine migration](/reference/machine-migration) or recovery on another host | Wiped. A new empty disk is created on the new host | |
| 34 | +| Machine cloned | The clone starts with an empty disk | |
| 35 | +| Cache disk removed from the config | Disk destroyed | |
| 36 | +| Machine destroyed | Disk destroyed | |
| 37 | + |
| 38 | +## Performance |
| 39 | + |
| 40 | +A cache disk has the same IOPS and bandwidth limits as a Fly Volume on the same Machine size. See [Volume limits](/volumes/overview#volume-limits) for the numbers. |
| 41 | + |
| 42 | +{/* TODO: say how this compares with the root file system (Rian: performance is the differentiator over rootfs). volumes/overview currently says rootfs is limited the same as volumes; confirm which is right. */} |
| 43 | + |
| 44 | +## Limits |
| 45 | + |
| 46 | +- One cache disk per Machine. |
| 47 | +- Available in all regions. |
| 48 | +- Maximum size is 51200 MiB (50 GiB). |
| 49 | +- Minimum size is 16 MiB. |
| 50 | +- The mount path must be an absolute path other than `/`, and it can't overlap `/dev`, `/proc`, `/sys`, `/.fly`, or a volume mount path on the same Machine. |
| 51 | + |
| 52 | +## Add a cache disk in fly.toml |
| 53 | + |
| 54 | +Add a `[[cache_disk]]` section to your app's `fly.toml`, then run `fly deploy`: |
| 55 | + |
| 56 | +```toml |
| 57 | +[[cache_disk]] |
| 58 | + size = "1gb" |
| 59 | + path = "/cache" |
| 60 | +``` |
| 61 | + |
| 62 | +- `size`: the disk size, with a unit, such as `512mb` or `1gb`. |
| 63 | +- `path`: where to mount the disk in the Machine. |
| 64 | +- `processes`: optional. The [process groups](/launch/processes) that get the cache disk. Without it, only Machines in the default process group get one. |
| 65 | + |
| 66 | +Each Machine can have only one cache disk, so a process group can match only one `[[cache_disk]]` entry. To remove the cache disk, delete the section and deploy again. |
| 67 | + |
| 68 | +{/* TODO: add the minimum flyctl version once a release includes flyctl#5469. */} |
| 69 | + |
| 70 | +## Add a cache disk with flyctl |
| 71 | + |
| 72 | +Use `--cache-disk-size` and `--cache-disk-path` with [`fly machine run`](/flyctl/cmd/fly_machine_run), [`fly machine create`](/flyctl/cmd/fly_machine_create), or [`fly machine update`](/flyctl/cmd/fly_machine_update): |
| 73 | + |
| 74 | +```bash |
| 75 | +fly machine update <machine-id> --cache-disk-size 1gb --cache-disk-path /cache |
| 76 | +``` |
| 77 | + |
| 78 | +To resize an existing cache disk, pass only `--cache-disk-size`. To remove it, set `--cache-disk-size 0`. |
| 79 | + |
| 80 | +## Add a cache disk with the Machines API |
| 81 | + |
| 82 | +Set `cache_disk` in the Machine config when you [create](/machines/api/machines-resource#create-a-machine) or [update](/machines/api/machines-resource#update-a-machine) a Machine: |
| 83 | + |
| 84 | +- `size_mb`: the disk size in MiB. |
| 85 | +- `path`: where to mount the disk in the Machine. The disk is formatted as ext4 and mounted at this path. |
| 86 | + |
| 87 | +```bash |
| 88 | +curl -i -X POST \ |
| 89 | + -H "Authorization: Bearer ${FLY_API_TOKEN}" -H "Content-Type: application/json" \ |
| 90 | + "${FLY_API_HOSTNAME}/v1/apps/my-app-name/machines" \ |
| 91 | + -d '{ |
| 92 | + "config": { |
| 93 | + "image": "registry-1.docker.io/library/ubuntu:latest", |
| 94 | + "guest": { |
| 95 | + "cpu_kind": "shared", |
| 96 | + "cpus": 1, |
| 97 | + "memory_mb": 256 |
| 98 | + }, |
| 99 | + "cache_disk": { |
| 100 | + "size_mb": 1024, |
| 101 | + "path": "/cache" |
| 102 | + } |
| 103 | + } |
| 104 | + }' |
| 105 | +``` |
| 106 | + |
| 107 | +This creates a Machine with a 1 GiB cache disk mounted at `/cache`. |
| 108 | + |
| 109 | +To resize the disk, update the Machine with a new `size_mb`. The old disk and its contents are discarded. To remove the disk, update the Machine config without `cache_disk`. |
| 110 | + |
| 111 | +See the [`fly.MachineCacheDrive`](/api/machines/models#fly-machinecachedrive) reference for the full schema. |
| 112 | + |
| 113 | +{/* TODO: the API reference still says cache_drive; check the schema name and anchor after the next spec refresh. */} |
| 114 | + |
| 115 | +## Pricing |
| 116 | + |
| 117 | +{/* TODO: pricing not decided yet. Add it here and in /about/pricing. */} |
| 118 | + |
| 119 | +## Related |
| 120 | + |
| 121 | +- [Fly Volumes overview](/volumes/overview) |
| 122 | +- [Machine migration](/reference/machine-migration) |
| 123 | +- [Databases & Storage](/database-storage-guides) |
0 commit comments