#Volume Snapshots

A Snapshot is a point-in-time, read-only copy of a Volume. Snapshots are designed for backup, rollback, and reproducible environments.

Snapshot Features#

  • Instant Creation: Built on Copy-on-Write semantics, snapshot creation is near-instant
  • Space Efficiency: Built on JuiceFS clone semantics (Copy-on-Write), so snapshots avoid full data copies
  • Fast Recovery: Restore operations quickly roll data back to a known state
  • Version Traceability: Snapshot names and descriptions support release workflows

Snapshot Lifecycle#

Create a Snapshot#

go
volume, err := client.CreateVolume(ctx, apispec.CreateSandboxVolumeRequest{
  AccessMode: apispec.NewOptVolumeAccessMode(apispec.VolumeAccessModeRWX),
  CacheSize:  apispec.NewOptString("1G"),
  BufferSize: apispec.NewOptString("128M"),
})
if err != nil {
  log.Fatal(err)
}
fmt.Printf("Volume ID: %s\n", volume.ID)

// Create snapshot with description
snapshot, err := client.CreateVolumeSnapshot(ctx, volume.ID, apispec.CreateSnapshotRequest{
  Name:        "v1.1-beta",
  Description: apispec.NewOptString("Feature: Added user authentication module"),
})
if err != nil {
  panic(err)
}
fmt.Printf("Snapshot created: %s (%s)\n", snapshot.ID, snapshot.Name)

List Snapshots#

ℹ

size_bytes is currently a logical metadata field from the API and may be 0. Use storage backend metrics for physical usage accounting.

go
snapshots, err := client.ListVolumeSnapshots(ctx, volume.ID)
if err != nil {
  panic(err)
}
fmt.Printf("Total snapshots: %d\n", len(snapshots))
for _, snap := range snapshots {
  fmt.Printf("  - %s: %s (size_bytes=%d)\n", snap.ID, snap.Name, snap.SizeBytes)
}

Get Snapshot Details#

go
snapshot, err = client.GetVolumeSnapshot(ctx, volume.ID, snapshot.ID)
if err != nil {
  panic(err)
}
fmt.Printf("Snapshot ID: %s\n", snapshot.ID)
fmt.Printf("Name: %s\n", snapshot.Name)
fmt.Printf("Description: %s\n", snapshot.Description.Value)
fmt.Printf("Size: %d bytes\n", snapshot.SizeBytes)
fmt.Printf("Created At: %s\n", snapshot.CreatedAt)

Restore a Snapshot#

Restoring a snapshot rolls the Volume data back to the point when the snapshot was created.

ℹ

The restore API returns 200 with {status: "restored"} on success. Runtime failures can include lock contention (409) and remount timeout (504).

ℹ

Restore is irreversible. All data changes made after the snapshot was created are lost. Create a new backup snapshot before restoring.

go
// Execute restore
result, err := client.RestoreVolumeSnapshot(ctx, volume.ID, snapshot.ID)
if err != nil {
  panic(err)
}
status := "restored"
if data, ok := result.Data.Get(); ok {
  status = data.Status.Or(status)
}
fmt.Printf("Volume restore status: %s\n", status)

Delete a Snapshot#

ℹ

Delete is idempotent in the current infra implementation: deleting an already-missing snapshot still returns success (deleted: true).

go
_, err = client.DeleteVolumeSnapshot(ctx, volume.ID, snapshot.ID)
if err != nil {
  panic(err)
}
fmt.Println("Snapshot deleted")
ℹ

Deleting a snapshot does not affect current Volume data. The live Volume state remains intact even if all snapshots are removed.

Next Steps#

Volume Fork

Clone a volume with Copy-on-Write isolation

Volume Mounts

Mount volumes to sandboxes for persistent data access

Volume Overview

Understand the full volume lifecycle and configuration