Lifecycle and tiering

How a "transition objects to GCS after 30 days, expire non-current versions after 60 days" rule turns into actual work in the cluster.

End-to-end

sequenceDiagram
    participant Op as Operator
    participant API as PutBucketLifecycleConfiguration
    participant Store as Bucket metadata
    participant SCAN as Data scanner
    participant ILM as Lifecycle evaluator
    participant TIER as warm-backend
    participant XL as xl-storage

    Op->>API: PUT lifecycle XML
    API->>Store: Persist + propagate to peers
    Note over SCAN: Every cycle (~hourly)
    SCAN->>XL: List objects + xl.meta
    SCAN->>ILM: Eval(rule, version)
    ILM-->>SCAN: Action
    alt Expire
        SCAN->>XL: Delete or convert to free version
    else Transition
        SCAN->>XL: Read payload
        SCAN->>TIER: Put on warm backend
        SCAN->>XL: Replace payload with tier handle
    end

Pieces involved

Step	File
HTTP entry	cmd/bucket-lifecycle-handlers.go
XML model	internal/bucket/lifecycle/
Scanner driver	cmd/data-scanner.go, cmd/global-heal.go
Action dispatch	cmd/bucket-lifecycle.go
Tier registry	cmd/tier.go, cmd/tier-handlers.go
Warm backends (S3 / Azure / GCS / MinIO)	cmd/warm-backend-*.go
Tier sweeper (orphan cleanup)	cmd/tier-sweeper.go
Audit	cmd/bucket-lifecycle-audit.go
Metrics	cmd/metrics-v3-ilm.go, cmd/tier-last-day-stats.go

Rule examples

Expire after 30 days

<Rule>
  <Status>Enabled</Status>
  <Filter><Prefix>backups/</Prefix></Filter>
  <Expiration><Days>30</Days></Expiration>
</Rule>

The scanner sees an object older than 30 days, calls lifecycle.Eval, gets ActionExpire, and either deletes outright (unversioned bucket) or writes a delete marker / free version (versioned bucket).

Transition + non-current expiry

<Rule>
  <Status>Enabled</Status>
  <Filter><Prefix>raw/</Prefix></Filter>
  <Transition>
    <Days>30</Days>
    <StorageClass>WARMS3</StorageClass>
  </Transition>
  <NoncurrentVersionExpiration>
    <NoncurrentDays>60</NoncurrentDays>
  </NoncurrentVersionExpiration>
</Rule>

The scanner transitions current versions older than 30 days to the WARMS3 tier (defined via mc admin tier add); after a non-current version is 60 days old, the scanner expires it. Tier-side cleanup is the responsibility of the tier sweeper (cmd/tier-sweeper.go).

Reading a tiered object

When an object's data is on the warm backend, xl.meta carries a "tier handle" instead of shard files. ObjectLayer.GetObject (cmd/erasure-server-pool.go) detects this and proxies the read through the warm backend. The client sees a normal GET — possibly with higher latency.

Tier types

Type	File	Notes
s3	cmd/warm-backend-s3.go	Any S3-compatible endpoint.
azure	cmd/warm-backend-azure.go	Azure Blob Storage.
gcs	cmd/warm-backend-gcs.go	Google Cloud Storage.
minio	cmd/warm-backend-minio.go	Another MinIO cluster.

Replication interactions

A bucket can be both replicated and lifecycle-managed:

• The replication subsystem replicates current versions before they transition.
• After transition, replication targets fetch from the tier on demand if needed.
• Delete markers from lifecycle expirations replicate as delete markers.

Test entry points

• make test-ilm — docs/bucket/replication/setup_ilm_expiry_replication.sh
• make test-ilm-transition — docs/bucket/lifecycle/setup_ilm_transition.sh

Where to start reading

• internal/bucket/lifecycle/lifecycle.go
• cmd/bucket-lifecycle.go
• cmd/tier.go
• cmd/warm-backend-s3.go (most generic of the warm backends)

See Lifecycle and tiering for the system-level view and Data scanner for what drives evaluations.