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 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

Each mount is defined as an UnderFileSystem custom resource. The fields are the same regardless of UFS type:

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:

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.

Use alluxio mount add to create a mount point, passing UFS-specific connection properties via --option:

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

Verify the mount is active:

bin/alluxio mount list

See each storage system's guide for the UFS-specific URI scheme and property names.

Mounting Multiple Buckets

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

Create one UnderFileSystem CR per location (see each UFS guide for the mountOptions properties), then apply them together:

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

Run alluxio mount add once per location:

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>

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:

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:

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

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.

Managing Existing Mounts

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

List mounts:

kubectl -n alx-ns get ufs

NAME         PHASE   AGE
alluxio-s3   Ready   13d

Remove a mount:

kubectl -n alx-ns delete ufs alluxio-s3

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

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:

# 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