# Underlying Storage

Alluxio connects to a wide variety of storage systems, known as Under File Systems (UFS), and exposes them through a single unified virtual namespace. This section explains how Alluxio mounts work and provides configuration guides for each supported storage system.

## How Mounts Work

A **mount** binds an Alluxio virtual path to a UFS URI. For example, mounting `s3://my-bucket/data/` to `/data` makes the bucket contents accessible at `/data` in the Alluxio namespace. Data is not copied — reads and writes are proxied through Alluxio to the underlying storage.

Key behaviors:

* Multiple storage systems can be mounted simultaneously under different paths.
* **Per-mount options** (set in `mountOptions` or `--option`) take precedence over global properties set in `AlluxioCluster` `spec.properties` or `alluxio-site.properties`.
* Mount points must be at the top level of the Alluxio namespace and cannot be nested. See [Mount Rules](#mount-rules) below.

## Mount Rules

When defining your namespace, you must follow two rules to ensure a valid and unambiguous mount table.

### Rule 1: Mounts Must Be Direct Children of the Root (`/`)

You can only create mount points at the top level of the Alluxio namespace. You cannot mount to the root path (`/`) itself, nor can you create a mount point inside a non-existent directory.

| Action              | Alluxio Path   | UFS Path                 | Valid? | Reason                                            |
| ------------------- | -------------- | ------------------------ | ------ | ------------------------------------------------- |
| Mount a bucket      | `/s3-data`     | `s3://my-bucket/`        | ✔️ Yes | Mount point is a direct child of root.            |
| Mount to root       | `/`            | `s3://my-bucket/`        | ❌ No   | The root path cannot be a mount point.            |
| Mount to a sub-path | `/data/images` | `s3://my-bucket/images/` | ❌ No   | Mount points cannot be created in subdirectories. |

### Rule 2: Mounts Cannot Be Nested

One mount point cannot be created inside another, either in the Alluxio namespace or in the UFS namespace. For example, if `/data` is mounted to `s3://my-bucket/data`, you cannot create a new mount at `/data/tables` (nested Alluxio path) or mount another UFS to `s3://my-bucket/data/tables` (nested UFS path).

Suppose you have an existing mount point:

* **Alluxio Path:** `/data`
* **UFS Path:** `s3://my-bucket/data`

The following new mounts would be **invalid**:

| New Alluxio Path | New UFS Path                 | Valid? | Reason for Rejection                                                                     |
| ---------------- | ---------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `/data/tables`   | `hdfs://namenode/tables`     | ❌ No   | The Alluxio path `/data/tables` is nested inside the existing `/data` mount.             |
| `/tables`        | `s3://my-bucket/data/tables` | ❌ No   | The UFS path `s3://.../data/tables` is nested inside the existing `s3://.../data` mount. |

## Basic Mount Setup

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
Each mount is defined as an `UnderFileSystem` custom resource. The fields are the same regardless of UFS type:

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: my-mount               # Unique name for this mount resource
  namespace: alx-ns            # Must match the AlluxioCluster namespace
spec:
  alluxioCluster: alluxio-cluster   # Name of the AlluxioCluster CR to attach to
  path: <UFS_URI>              # UFS URI, e.g. s3://bucket/prefix/ or gs://bucket/path/
  mountPath: /data             # Where this UFS appears in the Alluxio namespace
  mountOptions:                # UFS-specific connection and credential properties
    <property-key>: "<value>"
```

Apply and verify:

```shell
kubectl apply -f ufs.yaml
kubectl exec -n alx-ns alluxio-cluster-coordinator-0 -- alluxio mount list
```

See each storage system's guide for the UFS-specific values to use in `path` and `mountOptions`.
{% endtab %}

{% tab title="Docker / Bare-Metal" %}
Use `alluxio mount add` to create a mount point, passing UFS-specific connection properties via `--option`:

```shell
bin/alluxio mount add \
  --path /data \
  --ufs-uri <UFS_URI> \
  --option <property-key>=<value>
```

Verify the mount is active:

```shell
bin/alluxio mount list
```

See each storage system's guide for the UFS-specific URI scheme and property names.
{% endtab %}
{% endtabs %}

## Mounting Multiple Buckets

Each storage location requires its own mount with a unique `mountPath`. There is no hard limit on the number of mounts.

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
Create one `UnderFileSystem` CR per location (see each UFS guide for the `mountOptions` properties), then apply them together:

```shell
kubectl apply -f bucket-a.yaml -f bucket-b.yaml
```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}
Run `alluxio mount add` once per location:

```shell
bin/alluxio mount add --path /bucket-a --ufs-uri <UFS_URI_A> --option <key>=<value>
bin/alluxio mount add --path /bucket-b --ufs-uri <UFS_URI_B> --option <key>=<value>
```

{% endtab %}
{% endtabs %}

Per-mount credentials in `mountOptions` take precedence over global credentials, which is useful when mounts span multiple accounts or projects.

## Kubernetes: Credential Management

Avoid putting credentials directly in `UnderFileSystem` CR `mountOptions` — they end up in version-controlled YAML and must be repeated for every mount. Two alternatives set credentials once at the cluster level:

**Option A: `spec.properties` in the AlluxioCluster CR**

Set UFS credential properties globally. Individual mounts inherit them, and per-mount `mountOptions` still override when needed:

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  properties:
    # UFS-specific property names vary — see each UFS guide
    <credential-property-key>: "<credential-value>"
```

**Option B: Kubernetes Secret + pod environment variables**

Store credentials in a Secret to keep them out of version control, then inject them as environment variables that the UFS driver reads:

```shell
kubectl create secret generic ufs-credentials \
  --from-literal=credential-value=<YOUR_CREDENTIAL> \
  -n alx-ns
```

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  coordinator:
    env:
      - name: <ENV_VAR_NAME>   # UFS-specific — see each UFS guide
        valueFrom:
          secretKeyRef:
            name: ufs-credentials
            key: credential-value
  worker:
    env:
      - name: <ENV_VAR_NAME>
        valueFrom:
          secretKeyRef:
            name: ufs-credentials
            key: credential-value
```

For complete working examples with S3-specific property and environment variable names, see [Setting Credentials in Kubernetes](/ee-ai-en/ufs/s3.md#setting-credentials-in-kubernetes).

## Managing Existing Mounts

Once a mount is active, use the following commands to inspect or remove it.

{% tabs %}
{% tab title="Kubernetes (Operator)" %}

* **List mounts:**

  ```shell
  kubectl -n alx-ns get ufs
  ```

  ```console
  NAME         PHASE   AGE
  alluxio-s3   Ready   13d
  ```
* **Remove a mount:**

  ```shell
  kubectl -n alx-ns delete ufs alluxio-s3
  ```

  ```console
  underfilesystem.k8s-operator.alluxio.com "alluxio-s3" deleted
  ```

{% endtab %}

{% tab title="Docker / Bare-Metal" %}

* **List mounts:**

  ```shell
  bin/alluxio mount list
  ```
* **Remove a mount:**

  ```shell
  bin/alluxio mount remove --path /s3-data
  ```

{% endtab %}
{% endtabs %}

The mount table is stored in etcd. Alluxio components periodically poll etcd for the latest mount table, so additions and removals propagate automatically throughout the cluster.

## Common Object Store Settings

The following settings apply to all object store UFS types (S3, OSS, BOS, COS, TOS, and S3-compatible).

### Request Retry Policy

When the object store returns a transient error, Alluxio retries the request automatically. The following error codes are retried: `500`, `502`, `503 Slow Down`, and `504`. Client errors (`4xx`) are never retried.

Configure the retry behavior in `conf/alluxio-site.properties` or as mount options:

```properties
# Maximum number of retries per request
alluxio.underfs.business.retry.max.num=10

# Initial wait between retries
alluxio.underfs.business.retry.base.sleep=30ms

# Maximum wait between retries (default: 30s)
alluxio.underfs.business.retry.max.sleep=60s
```

## Supported Storage Systems

### Cloud Object Storage

| Storage System                         | Description                                                   | Guide                                           |
| -------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------- |
| **Amazon S3**                          | The standard guide for connecting to Amazon S3.               | [View Guide](/ee-ai-en/ufs/s3.md)               |
| **Google Cloud Storage (GCS)**         | Guide for connecting to Google Cloud Storage.                 | [View Guide](/ee-ai-en/ufs/gcs.md)              |
| **Azure Blob Storage**                 | Guide for connecting to Azure Blob Storage.                   | [View Guide](/ee-ai-en/ufs/azure-blob-store.md) |
| **Alibaba Cloud OSS**                  | Guide for connecting to Alibaba Cloud Object Storage Service. | [View Guide](/ee-ai-en/ufs/aliyun-oss.md)       |
| **Tencent Cloud Object Storage (COS)** | Guide for connecting to Tencent Cloud's object storage.       | [View Guide](/ee-ai-en/ufs/cos.md)              |
| **Baidu Object Storage (BOS)**         | Guide for connecting to Baidu Cloud's object storage.         | [View Guide](/ee-ai-en/ufs/bos.md)              |
| **Volcengine TOS**                     | Guide for connecting to Volcengine's object storage.          | [View Guide](/ee-ai-en/ufs/tos.md)              |

### On-Premises Storage

| Storage System                            | Description                                                                             | Guide                                        |
| ----------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------- |
| **S3-Compatible**                         | For connecting to object stores that use the S3 API, such as MinIO or Ceph.             | [View Guide](/ee-ai-en/ufs/s3-compatible.md) |
| **Hadoop Distributed File System (HDFS)** | The standard guide for connecting to an HDFS cluster.                                   | [View Guide](/ee-ai-en/ufs/hdfs.md)          |
| **Network Attached Storage (NAS)**        | For connecting to any POSIX-compliant file system mounted on your cluster, such as NFS. | [View Guide](/ee-ai-en/ufs/nas.md)           |


---

# 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/ufs.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.