Cost Optimization with Storage Tiers

Most Crab repositories follow a heavy-tail access pattern: a small hot set of files is read continuously while a long cold tail is rarely touched. Without lifecycle rules, every byte pays the Standard-tier rate regardless of access frequency.

Crab's tiering system generates provider-specific lifecycle rules that automatically transition cold xorbs through cheaper storage classes on a configurable schedule.

How It Works

crab tier plan generates lifecycle rules scoped to the .crab/xorbs/ prefix only. Metadata (shards, file-index, refs, manifests) is never tiered — it must stay warm for fast access.

Plan lifecycle rules

1. Preview the lifecycle plan

crab tier plan

Read-only — probes the bucket and prints what Crab would apply. No write credentials needed.

2. Apply the plan

crab tier plan --apply

Crab requires a provider conditional-write guard before lifecycle mutation, writes a backup of the current configuration, submits the new rules, and requires an equivalent provider read-back before reporting success. The S3 lifecycle API has no conditional write, and GCS/Azure safe prefix-preserving write paths are not wired, so the CLI currently renders plans but fails closed on lifecycle apply for all three providers.

3. Roll back if needed

crab tier rollback .crab/tier/backups/2026-04-27T20:00:00Z-pre-apply.json

Restores the previous lifecycle configuration.

Configuration

All tiering settings live under [tier] in .crab/local.toml:

[tier]
enabled = true
to_ia_days = 30          # Days before warm transition
to_deep_days = 180       # Days before cold transition
noncurrent_days = 30     # Noncurrent version expiration
restore_tier = "standard"
restore_duration_days = 7

Restore-Aware Hydration

When crab hydrate encounters an archived xorb, it automatically initiates a restore and polls until the object is readable:

# Hydrate with default restore tier
crab hydrate --all

# Use expedited restore for urgent access
crab hydrate --all --restore-tier=expedited

# Fail immediately on archived objects (no restore)
crab hydrate --all --no-restore

Restore Availability by Storage Class

Merge Mode

If your bucket has existing lifecycle rules (from Terraform, CloudFormation, etc.), use --merge to preserve them:

crab tier plan --apply --merge

With --merge, Crab replaces only rules with crab- prefixed IDs and leaves all other rules untouched.

Minimum Retention Periods

Deleting an object before its minimum retention period incurs an early-deletion penalty. crab gc blocks early deletes by default and reports the estimated cost.

Rollback and Safety

Every supported tier plan --apply writes a backup before modifying the bucket:

.crab/tier/backups/<RFC3339-ts>-pre-apply.json

New backups record both the previous and applied documents. Rollback validates the provider and fails if the current policy drifted, then restores the previous document or deletes the policy when none existed before apply. Providers without a conditional lifecycle write are rejected before a backup or mutation. Dry-run writes no backup.

Common Workflow

# 1. Baseline cost snapshot
crab doctor --cost --json > before.json

# 2. Review the plan
crab tier plan

# 3. Apply
crab tier plan --apply

# 4. Wait for S3 lifecycle evaluation (~24h)

# 5. Compare costs
crab doctor --cost --json > after.json

CLI Reference

For complete command syntax and all available flags, see the crab tier reference.