Cache Eviction

Data leaves the Alluxio cache in three ways:

1. Automatic eviction — workers evict data when cache fills up, ordered by the configured policy (LRU by default)

2. TTL expiry — background scan removes data whose lifetime has elapsed, regardless of access or priority

3. Manual eviction — job free explicitly purges a path on demand

Automatic Eviction

When a worker needs space for new data, it runs an evictor to select which cached pages to remove. Three policies are available:

Policy	Evicts
LRU (default)	Data not accessed for the longest time
LFU	Data accessed the fewest times overall
FIFO	Data written earliest

To change the eviction policy, set in alluxio-site.properties on all workers:

# Use LFU instead of the default LRU
alluxio.worker.page.store.evictor.type=LFU

Asynchronous Eviction

By default, eviction runs synchronously during writes, which can add latency. Asynchronous eviction runs in the background to keep headroom available before the cache fills up:

alluxio.worker.page.store.async.eviction.enabled=true
# start evicting when cache usage exceeds this threshold (default: 0.9)
alluxio.worker.page.store.async.eviction.high.watermark=0.85
# stop evicting when cache usage drops below this threshold (default: 0.8)
alluxio.worker.page.store.async.eviction.low.watermark=0.75
# how often to check cache usage (default: 1min)
alluxio.worker.page.store.async.eviction.check.interval=30s

TTL-based eviction and Cache Priority also affect what gets evicted and when. See Cache Policies for details.

Manual Eviction: The free Job

Use job free to explicitly purge a path from the cache — without touching the underlying UFS data. For every file under the path, free removes both the cached data (pages) and the cached metadata (file status) from all workers, so the next access re-fetches everything from the UFS. Common scenarios:

• Model version update: free the old version before (or after) loading the new one

• Post-job cleanup: release space after a batch job completes

• Force re-cache: free then reload to pick up UFS changes for an immutable-policy path

• Out-of-band UFS changes: files deleted, overwritten, or changed directly in the UFS leave stale data and metadata behind — see Cache Invalidation for the full decision guide

If your goal is consistency with the UFS rather than reclaiming space — stale reads or errors after data changed outside Alluxio — start at Cache Invalidation. It covers when a policy will refresh the data on its own, and which of job free and index invalidate to reach for.

Submit and Monitor

Kubernetes (Operator)

# Submit (returns immediately)
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <ufs-or-alluxio-path> --submit

# Monitor progress
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <ufs-or-alluxio-path> --progress

Docker / Bare-Metal

# Submit (returns immediately)
bin/alluxio job free --path <ufs-or-alluxio-path> --submit

# Monitor progress
bin/alluxio job free --path <ufs-or-alluxio-path> --progress

Example progress output:

Progress for Free path file '<path>':
    Job Id: b21ce9fb-f332-4d39-8bb4-554f9a4fa601
    Job Submitted: Fri Feb 02 21:28:56 CST 2024
    Job path: <path>
    Job State: SUCCEEDED, finished at Fri Feb 02 21:29:01 CST 2024
    Free Info:  totalFile:4 totalByte:3072.00KB
    Free Files Failed: 0
    Free Bytes Failed: 0B
    Free Files Succeeded: 4
    Free Bytes Succeeded: 3072.00KB

Stop a Running Free Job

Kubernetes (Operator)

kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <ufs-or-alluxio-path> --stop

Docker / Bare-Metal

bin/alluxio job free --path <ufs-or-alluxio-path> --stop

Stopping leaves partially-freed data in the cache. The job can be resumed by submitting it again with --submit.

Version Update Pattern

To replace a pinned dataset with a newer version:

Kubernetes (Operator)

# 1. Remove priority pin from old version
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio priority remove --path <old-version-path>

# 2. Free old version from cache
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job free --path <old-version-path> --submit

# 3. Load and pin new version
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio job load --path <new-version-path> --submit --verify
kubectl exec -n <NAMESPACE> alluxio-cluster-coordinator-0 -- \
  alluxio priority add --path <new-version-path> --priority high

Docker / Bare-Metal

# 1. Remove priority pin from old version
bin/alluxio priority remove --path <old-version-path>

# 2. Free old version from cache
bin/alluxio job free --path <old-version-path> --submit

# 3. Load and pin new version
bin/alluxio job load --path <new-version-path> --submit --verify
bin/alluxio priority add --path <new-version-path> --priority high

For a complete list of job free flags, see the job free CLI reference.

You can also trigger and manage free jobs via the REST API.

Stale Cache Cleaning

Cluster topology changes can leave data cached on workers that no longer "own" that data according to the consistent hash ring. This stale data consumes space but is never served to clients.

When this happens:

• Workers are added or removed (ownership redistributes)

• A file's replication factor is reduced

• A worker goes offline temporarily and its data migrates, then it rejoins

Trigger Stale Cleaning

curl -X POST <coordinator-host>:<coordinator-api-port>/api/v1/cache \
  -d '{"op":"clear-stale"}' \
  -H "Content-Type: application/json"

This submits an async job to each worker. Workers scan local storage, verify ownership against the current hash ring, and delete any data they no longer own. Monitor progress via the alluxio_cleared_stale_cached_data Prometheus metric or worker logs.

For more details, see the REST API reference.

Mass file deletion from stale cleaning can create metadata I/O pressure that delays Worker Pod termination. Run during a maintenance window on large clusters.