Skip to content

Add cache disks page - #2655

Draft
kcmartin wants to merge 3 commits into
mainfrom
cache-drives-doc
Draft

kcmartin wants to merge 3 commits into
mainfrom
cache-drives-doc

Conversation

@kcmartin

@kcmartin kcmartin commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

New page for Machine cache disks: lifecycle, performance, limits, and setup with fly.toml, flyctl (flyctl#5469), and the Machines API.

Not ready to merge: pricing and the rootfs performance comparison are still TODOs. Tracking: https://github.com/superfly/docs-tracking/issues/394

@mintlify

mintlify Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
fly-io 🟢 Ready View Preview Nov 17, 2026, 1:10 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

@mintlify

mintlify Bot commented Nov 13, 2026

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
fly-io 🟡 Building – Nov 13, 2026, 11:36 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

Comment thread machines/cache-drives.mdx Outdated
| | Root file system | Cache drive | Fly Volume |
| --- | --- | --- | --- |
| Survives stop and restart | No | Usually, not guaranteed | Yes |
| Survives a move to another host | No | No | Volumes don't move between hosts |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do migrate volumes between hosts as part of https://docs.fly.io/reference/machine-migration

"migration" might be a better word than move?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to "Machine migration" with a link, and fixed the volume cell, in a045b42.

Comment thread machines/cache-drives.mdx Outdated
| Machine update that doesn't change the cache drive's size | Usually kept |
| Cache drive `path` changed | Kept |
| Cache drive `size_mb` changed | Wiped. The drive is destroyed and a new empty one is created |
| Machine moved or recovered on another host | Wiped. A new empty drive is created on the new host |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here - call this migration too?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to "Machine migration" with a link, and fixed the volume cell, in a045b42.

Comment thread machines/cache-drives.mdx Outdated
}'
```

This creates a Machine with a 10 GiB cache drive mounted at `/cache`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't want excessive allocations through people copying the example. Let's give a small size - 1 GiB?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now 1 GiB in a045b42.

@kcmartin kcmartin changed the title Add cache drives page Add Cache disks page Nov 16, 2026
@kcmartin kcmartin changed the title Add Cache disks page Add cache disks page Nov 17, 2026

This branch was successfully deployed

1 active deployment
staging — 5ce7f241 Deployed Nov 17, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants