# How Alluxio Works

This page explains the fundamental concepts behind Alluxio's architecture and capabilities. Understanding these ideas will help you get the most out of the system.

## 1. Decentralized Architecture

Alluxio is built on a **decentralized, Master-less architecture** where **metadata** (file locations, directory structure, and namespace mappings) ownership is distributed across all Workers via **consistent hashing**. Clients communicate directly with the responsible Worker in a single network hop — with no central authority involved.

This decentralized design provides several key advantages:

* **No Single Point of Failure:** The system remains available even if some Worker nodes fail.
* **Linear Scalability:** Metadata and data capacity scale horizontally as you add more Workers.
* **Low Latency:** Clients resolve metadata and data locations in a single network hop.

### The Consistent Hash Ring

Alluxio uses a consistent hashing algorithm to map file paths to Workers. Imagine a virtual "hash ring" where all Workers in the cluster are placed — each Worker owns a segment of this ring and is responsible for the metadata and cached data of files that hash into its segment.

Each Worker owns multiple **virtual nodes (vnodes)** on the ring, computed deterministically from its UUID (a unique identifier assigned when the Worker first starts). This ensures even distribution across Workers and predictable placement: the same UUID always maps to the same ring slots.

To keep every client's view of the ring consistent, Alluxio uses **etcd** — a distributed key-value store — to manage cluster membership and track which Workers are online. etcd is a required infrastructure component for any Alluxio deployment. When deploying on Kubernetes, the Alluxio Operator provisions and manages etcd automatically as part of the cluster; see [Kubernetes Installation](https://documentation.alluxio.io/ee-ai-en/start/installing-on-kubernetes).

{% hint style="info" %}
The open-source version of Alluxio used a central **Master** node as the sole metadata service — a design that introduced a single point of failure, metadata bottlenecks under high concurrency, and increased latency on every I/O operation. Alluxio's enterprise architecture eliminates the Master node from the I/O path entirely. See the [Architecture White Paper](https://www.alluxio.io/whitepaper/alluxio-architecture-a-decentralized-data-acceleration-layer-for-the-ai-era) for the full design rationale.
{% endhint %}

### Key Components

1. **Alluxio Worker:** Co-located with compute (e.g., on the same Kubernetes node). Stores cached data in local storage (memory, SSD, or HDD) and manages the metadata for its portion of the namespace.
2. **Alluxio Client:** A library embedded in the compute framework. Contains the consistent hashing logic to locate the correct worker for any given file path, enabling direct client-to-worker communication without any central coordinator. **Alluxio FUSE** is a special form of this client: a long-running process that maps Linux VFS operations (open, read, write, etc.) to Alluxio operations, exposing a local mount point so any application can access Alluxio through standard file system calls without code changes.
3. **Alluxio Coordinator:** Unlike the former Master node, the Coordinator is never in the I/O critical path. It handles background cluster operations including Worker registration and health monitoring, cache preload and eviction job scheduling, and cluster configuration management. All data and metadata reads bypass the Coordinator entirely.

> For a deeper dive into the architecture, read the [Alluxio Architecture White Paper](https://www.alluxio.io/whitepaper/alluxio-architecture-a-decentralized-data-acceleration-layer-for-the-ai-era).

## 2. Unified Namespace

Alluxio provides a **unified namespace** that presents all your connected storage systems as a single, logical file system. This is achieved by "mounting" different Under File Systems (UFS) to paths within Alluxio.

For example, you can mount an S3 bucket and a GCS bucket into Alluxio:

<figure><img src="https://903014663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7DicXrir64osDa951OPc%2Fuploads%2Fgit-blob-641517d8af446960e9acccda6e3451f279f411bb%2Fnamespace.png?alt=media" alt=""><figcaption></figcaption></figure>

The mount table would look like this:

| Alluxio Path | Under File System (UFS) Path |
| ------------ | ---------------------------- |
| `/s3/`       | `s3://bucketA/data/`         |
| `/gcs/`      | `gcs://bucketB/records/`     |

Now, your applications can access data from both S3 and GCS through a single, consistent API without explicitly providing credentials or other system-specific information for each underlying storage system. The mapping between Alluxio paths and UFS paths is stored in a **mount table**, kept in **etcd** to ensure it is highly available and consistent across all Alluxio components.

> For a deeper dive, see [Connecting to Storage](https://documentation.alluxio.io/ee-ai-en/ufs).

## 3. Client Access Methods

Alluxio exposes three standard access protocols so applications can connect without code changes:

| API               | Protocol               | Best For                                                        |
| ----------------- | ---------------------- | --------------------------------------------------------------- |
| **POSIX (FUSE)**  | Linux filesystem mount | AI/ML training frameworks, any app that reads files from a path |
| **S3 API**        | HTTP / S3-compatible   | Apps already using the S3 SDK; no code change required          |
| **Python FSSpec** | Python                 | PyTorch DataLoader, HuggingFace Datasets, pandas                |

All three protocols are served by the same Alluxio workers and share the same underlying cache. The choice of API is a matter of integration preference, not performance.

> For configuration and usage, see [Client APIs](https://documentation.alluxio.io/ee-ai-en/data-access).

## 4. Fault Tolerance and Elastic Scaling

### UFS Fallback

When a worker becomes unavailable, the Alluxio FUSE client automatically falls back to reading data directly from the Under File System. Applications continue without interruption — the fallback is transparent to the caller.

### Elastic Scaling

Because Alluxio uses consistent hashing, workers can be added or removed at any time without service interruption:

* **Scale out (active):** A new worker joins the hash ring and takes over a portion of the range. Operations in its range succeed immediately, with data loading from UFS on first access.
* **Scale in (planned or failure):** When a worker is removed or fails, reads in its range fall back to UFS until the cluster rebalances. The hash ring can operate in **dynamic mode** (default — ring adjusts to online workers only) or **static mode** (ring retains offline workers to preserve cache affinity during short-term planned maintenance).

> For hash ring tuning and worker lifecycle operations, see [Hash Ring and Worker Lifecycle](https://documentation.alluxio.io/ee-ai-en/administration/managing-ring).

## 5. Worker Storage: The Page Store

Each worker stores cached data in a local **page store**. Files are split into fixed-size **pages** (4 MiB by default) and cached at page granularity — so a worker often holds only the portions of a file that applications have actually read. Whether a file is fully or partially cached depends on the access pattern.

The page store is typically backed by local SSDs for high throughput. A worker can configure multiple local directories so the page store spans multiple disks — each directory maps to one disk, and the worker distributes pages across them. Some deployments prefer a single logical volume and use RAID 0 across disks instead. Cache capacity is configured per worker and is independent of the UFS size.

The page store is a single flat tier — there is currently no built-in hot/cold tiering between memory and disk, or between SSD and HDD classes. All cached pages reside in the configured page store directories.

> For page store configuration (hostPath vs PVC, sizing, multi-disk, heterogeneous workers), see [Worker Configuration — Worker Storage](https://documentation.alluxio.io/ee-ai-en/administration/managing-worker#id-1.-worker-storage).

## 6. The Data Cache Lifecycle

Alluxio caches data on worker nodes co-located with compute. This co-location is the source of its performance advantage:

* **Cache hit:** Data is served from the worker's local storage (memory or NVMe SSD) — typically 10–100× faster than reading from a remote object store.
* **Cache miss:** The worker fetches the data from the UFS, stores it locally, and serves it to the client. Subsequent reads of the same data are served from cache.

The lifecycle of cached data has three phases:

### Loading Data

Data enters the cache in two primary ways: **on-demand** (passively) when an application first reads it, which is the default; or **proactively** via preloading jobs that warm up the cache in anticipation of future workloads, ensuring initial requests are served at memory speed.

### Managing Data

Once in cache, data lifecycle is governed by flexible policies. Administrators can define rules to control **what data gets cached**, set **storage quotas** for fair resource allocation between tenants, and apply **time-to-live (TTL)** settings to automatically purge stale data.

### Removing Data

When the cache is full, **automatic eviction** removes items based on a configured policy (e.g., Least Recently Used / LRU) to make room for new data. **Manual eviction** allows administrators to explicitly free specific files or directories.

> For a deeper dive, see [Cache Lifecycle](https://documentation.alluxio.io/ee-ai-en/cache).

## 7. Multi-Tenancy and Cluster Federation

For large enterprise environments, Alluxio supports multi-tenancy and federation of multiple clusters.

* **Multi-Tenancy:** Alluxio enforces tenant isolation, allowing different teams or business units to share a single deployment securely. This includes per-tenant cache quotas, access policies, and configurations. Authentication and authorization are handled through integrations with enterprise identity providers such as Okta and policy engines such as OPA.
* **Cluster Federation:** When you have multiple Alluxio clusters (e.g., one per region or business unit), a central **Management Console** and **API Gateway** provide a unified view for monitoring, licensing, and operations.

> For a deeper dive, see [Multi-Tenancy and Federation](https://documentation.alluxio.io/ee-ai-en/administration/managing-alluxio#id-3.-multi-tenancy-and-federation).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-en/how-alluxio-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.