# 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](https://documentation.alluxio.io/ee-ai-en/s3#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](https://documentation.alluxio.io/ee-ai-en/ufs/s3)               |
| **Google Cloud Storage (GCS)**         | Guide for connecting to Google Cloud Storage.                 | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/gcs)              |
| **Azure Blob Storage**                 | Guide for connecting to Azure Blob Storage.                   | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/azure-blob-store) |
| **Alibaba Cloud OSS**                  | Guide for connecting to Alibaba Cloud Object Storage Service. | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/aliyun-oss)       |
| **Tencent Cloud Object Storage (COS)** | Guide for connecting to Tencent Cloud's object storage.       | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/cos)              |
| **Baidu Object Storage (BOS)**         | Guide for connecting to Baidu Cloud's object storage.         | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/bos)              |
| **Volcengine TOS**                     | Guide for connecting to Volcengine's object storage.          | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/tos)              |

### 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](https://documentation.alluxio.io/ee-ai-en/ufs/s3-compatible) |
| **Hadoop Distributed File System (HDFS)** | The standard guide for connecting to an HDFS cluster.                                   | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/hdfs)          |
| **Network Attached Storage (NAS)**        | For connecting to any POSIX-compliant file system mounted on your cluster, such as NFS. | [View Guide](https://documentation.alluxio.io/ee-ai-en/ufs/nas)           |