Fly.Volume reference

MountVolume

Source: src/Fly/MountVolume.ts

Create a per-replica Fly Volume and mount it into a Service.

There is no standalone Volume resource. From a Machine, pass mounts: [{ path, sizeGb }] instead.

MountVolume: Mount into a Service

Yield MountVolume inside init. App and region come from the parent Service. Provide MountVolumeLive. At runtime you get disk.path.

A Volume attaches to one Machine. count: 3 creates three Volumes in one name-group, one per replica.

export default class Api extends Fly.Service<Api>()(
  "Api",
  { app: Site, main: import.meta.url, region: "iad", count: 3, port: 3000 },
  Effect.gen(function* () {
    const disk = yield* Fly.MountVolume({ path: "/data", sizeGb: 1 });
    const fs = yield* FileSystem.FileSystem;
    return {
      fetch: Effect.gen(function* () {
        const text = yield* fs.readFileString(`${disk.path}/hello.txt`);
        return HttpServerResponse.text(text);
      }),
    };
  }).pipe(Effect.provide(Fly.MountVolumeLive)),
) {}

MountVolume: Grow a disk

sizeGb can grow in place via extendVolume. Fly cannot shrink a Volume. Minimum size is 1 GB.

const disk = yield* Fly.MountVolume({ path: "/data", sizeGb: 10 });

MountVolume: Encryption

encrypted encrypts the Volume at rest.

const disk = yield* Fly.MountVolume({
  path: "/data",
  sizeGb: 1,
  encrypted: true,
});

Create-only

Flipping encrypted later is ignored.

MountVolume: Filesystem

fstype is the filesystem (ext4, …).

const disk = yield* Fly.MountVolume({
  path: "/data",
  sizeGb: 1,
  fstype: "ext4",
});

Create-only

Flipping fstype later is ignored.

MountVolume: Scheduled snapshots

Scheduled snapshots default on (autoBackupEnabled). snapshotRetention is days and updates in place. An on-demand snapshot is VolumeSnapshot.

const disk = yield* Fly.MountVolume({
  path: "/data",
  sizeGb: 1,
  autoBackupEnabled: true,
  snapshotRetention: 5,
});

MountVolume: Restore from a snapshot

snapshotId restores into a new disk.

const disk = yield* Fly.MountVolume({
  path: "/data",
  sizeGb: 1,
  snapshotId: Nightly.snapshotId,
});

Create-only

Changing snapshotId later is ignored.

MountVolume: Fork a volume

sourceVolumeId forks from an existing Volume.

const disk = yield* Fly.MountVolume({
  path: "/data",
  sizeGb: 1,
  sourceVolumeId: box.mounts[0].volumeId,
});

Create-only

Changing sourceVolumeId later is ignored.

MountVolume: Unique zone

requireUniqueZone asks Fly to land the Volume in a unique zone.

const disk = yield* Fly.MountVolume({
  path: "/data",
  sizeGb: 1,
  requireUniqueZone: true,
});

Create-only

Flipping requireUniqueZone later is ignored.

MountVolume: Volume name

name is the Fly volume-group name. If omitted, a unique name is generated from the host’s logical ID and path.

const disk = yield* Fly.MountVolume({
  path: "/data",
  sizeGb: 1,
  name: "api_data",
});

VolumeSnapshot

Source: src/Fly/VolumeSnapshot.ts

A Fly.VolumeSnapshot is an on-demand snapshot of a mounted disk.

Create is fire-and-forget. Identity is the snapshot id from a subsequent list. Destroy is a no-op. Snapshots follow Volume retention. nuke skips this type.

VolumeSnapshot: Create a snapshot

Point it at a Volume id from the parent Machine or Service (mounts[0].volumeId).

const box = yield* Fly.Machine("Box", {
  app: Site,
  region: "iad",
  image: "nginx:alpine",
  mounts: [{ path: "/data", sizeGb: 1 }],
});

export const Nightly = Fly.VolumeSnapshot("Nightly", {
  app: Site,
  volumeId: box.mounts[0].volumeId,
});

Changing app or volumeId replaces the snapshot

A new snapshot is created. There is no delete API for the old one. It follows Volume snapshot_retention.

VolumeSnapshot: Restore

Restore into a new disk with snapshotId on the mount. Create-only. The new Machine gets a copy. The original Volume is unchanged.

const restored = yield* Fly.Machine("Restored", {
  app: Site,
  region: "iad",
  image: "nginx:alpine",
  mounts: [{ path: "/data", sizeGb: 1, snapshotId: Nightly.snapshotId }],
});

VolumeSnapshot: Restore into a Service

Pass snapshotId on MountVolume. Same create-only rule.

export default class Api extends Fly.Service<Api>()(
  "Api",
  { app: Site, main: import.meta.url, region: "iad", port: 3000 },
  Effect.gen(function* () {
    const disk = yield* Fly.MountVolume({
      path: "/data",
      sizeGb: 1,
      snapshotId: Nightly.snapshotId,
    });
    return {
      fetch: Effect.succeed(HttpServerResponse.text(disk.path)),
    };
  }).pipe(Effect.provide(Fly.MountVolumeLive)),
) {}