Skip to content

Commit a045b42

Browse files
committed
Cache disks: rename, add fly.toml and flyctl setup, performance, review fixes
1 parent e7c6c0b commit a045b42

3 files changed

Lines changed: 124 additions & 93 deletions

File tree

‎docs.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -578,7 +578,7 @@
578578
"root": "machines/index",
579579
"pages": [
580580
"machines/overview",
581-
"machines/cache-drives",
581+
"machines/cache-disks",
582582
{
583583
"group": "Machines API",
584584
"root": "machines/api/index",

‎machines/cache-disks.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
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)

‎machines/cache-drives.mdx‎

Lines changed: 0 additions & 92 deletions
This file was deleted.

0 commit comments

Comments
 (0)