Tiered Storage

Starting with JuiceFS 1.4, tiered storage lets you map individual files or directories to different object storage classes (Storage Classes). For example, keep hot data in Standard storage and move cold data to Infrequent Access (IA) or Glacier‑class storage to save costs.

Key concepts

• tier-id: The tier identifier, ranging from 0 to 3.
  • 0 is the default tier (reserved value).
  • 1 to 3 are user‑configurable tiers.
• tier-sc: The storage class assigned to a tier-id, for example, STANDARD_IA, INTELLIGENT_TIERING, or GLACIER_IR.
• Tier attribute on a file/directory: Stored in metadata; it determines which storage class is used for subsequent writes or object migrations.

Prerequisites

1. The JuiceFS volume must be formatted and mounted.
2. The underlying object storage must support the target storage class and, if needed, the restoration of archived objects.
3. Define the tier mapping with juicefs config before running juicefs tier set.

1. Configure tier mappings

Assign a storage class to each tier (1 to 3):

juicefs config redis://localhost --tier-id 1 --tier-sc STANDARD_IA -y
juicefs config redis://localhost --tier-id 2 --tier-sc INTELLIGENT_TIERING -y
juicefs config redis://localhost --tier-id 3 --tier-sc GLACIER_IR -y

List the current mappings:

juicefs tier list redis://localhost

id=0 is always displayed as default.

2. Set a tier on a file or directory

A single file

juicefs tier set redis://localhost --id 1 /path/to/file

A directory (non‑recursive, only the directory entry)

When you set a storage tier on a directory, any new files or subdirectories created inside it later will inherit the tier-id of the parent directory, automatically using the corresponding storage type.

juicefs tier set redis://localhost --id 2 /path/to/dir

Without -r, only the directory inode is updated; files and subdirectories inside it are unchanged.

A directory (recursive)

juicefs tier set redis://localhost --id 2 /path/to/dir -r

Recursive mode processes all files and subdirectories under the target directory.

Reset to the default tier (tier 0)

juicefs tier set redis://localhost --id 0 /path/to/file
juicefs tier set redis://localhost --id 0 /path/to/dir -r

3. Rewrite objects after a mapping change (--force)

If you change a tier-id's tier-sc from A to B, the files' metadata tier‑id remains unchanged, but the objects in object storage are still stored as A.

Use --force to trigger a re-write, copying the objects to the new storage class:

juicefs tier set redis://localhost --id 2 /path/to/dir -r --force

4. Restore archive objects

For archive storage classes such as GLACIER or DEEP_ARCHIVE, issue a restore request with:

juicefs tier restore redis://localhost /path/to/dir -r

tier restore only sends the restore request to the object storage service. Whether and when the objects become readable depends on the provider's restore duration. The active copy remains available for 3 days (default).

5. Checking tier status

Use juicefs info to inspect the tier information of a file:

juicefs info /mountpoint/path/to/file

Key fields to look for:

• tier: <id>-><storage-class> — the tier-id stored in metadata and its mapped storage class.
• restore-status — indicates whether the object is in an unfrozen state and when the active copy expires.
• expected(...),actual(...) — shown when the metadata mapping and the object's actual storage class differ. This signals that tier set --force is needed to rewrite the objects.
• actual(...) — shown for files with tier-id=0, displaying the object's actual storage class.

Notes

• tier set only accepts file and directory paths.
• --id accepts values 0 to 3; when using --tier-id in configuration, only 1 to 3 are allowed.
• In writeback-cache mode (--writeback), tier set may fail if the file's data has not yet been uploaded to object storage. Wait for the upload to complete, then retry.
• Changing --tier-sc does not automatically migrate existing objects. You must run tier set ... --force manually.