Managing the Namespace

Overview of the Unified Namespace

Alluxio's unified namespace feature allows you to connect multiple, disparate storage systems (known as Under File Systems, or UFS) and present them as a single, logical file system to your applications. This is achieved by mounting UFS paths to paths within the Alluxio namespace.

This powerful feature simplifies data access by:

• Abstracting Storage: Applications don't need to know the specific location or credentials for each data source.

• Providing a Single API: Access data from S3, HDFS, GCS, and more through a consistent interface (e.g., FUSE, S3 API).

• Centralizing Management: Manage all your data connections from one place.

How Mounting Works

The mapping between Alluxio paths and UFS paths is stored in a mount table. To ensure this table is highly available and consistent across all Alluxio components (clients, workers), it is stored in a distributed key-value store, etcd.

Alluxio components periodically poll etcd for the latest mount table, so any changes are automatically propagated throughout the cluster.

Configuration for the Mount Table

To use etcd for your mount table, add the following properties to alluxio-site.properties:

Property	Description	Default
alluxio.mount.table.source	The backend for storing the mount table.	ETCD
alluxio.etcd.endpoints	A comma-separated list of connection URIs for your etcd cluster.	http://localhost:2379
alluxio.mount.table.etcd.polling.interval.ms	How often Alluxio components poll etcd for mount table updates.	3s

Managing Mount Points (Operations)

You can manage mount points using the bin/alluxio mount command-line interface.

Listing Mounts

To see all currently configured mount points:

bin/alluxio mount list

Adding a Mount

To mount a UFS path to an Alluxio path:

# Example: Mount an S3 bucket to /s3/ in Alluxio
bin/alluxio mount add --path /s3/ --ufs-uri s3://my-bucket/data/

Removing a Mount

To unmount a path:

bin/alluxio mount remove --path /s3/

Note: It may take a few seconds for changes to propagate to all clients and workers, depending on the polling.interval setting.

Configuring UFS Credentials and Properties

To access a UFS, Alluxio needs the correct configuration, especially security credentials. You can provide these in two ways.

Option 1: Global Configuration (Simple)

For simple setups where all mounts of a certain type (e.g., all S3 mounts) share the same credentials, you can set the properties globally in alluxio-site.properties.

# alluxio-site.properties

# Configure credentials for ALL S3 mounts
s3a.accessKeyId=<S3_ACCESS_KEY>
s3a.secretKey=<S3_SECRET_KEY>
alluxio.underfs.s3.region=us-east-1

# Configure settings for ALL HDFS mounts
alluxio.underfs.hdfs.configuration=/path/to/core-site.xml:/path/to/hdfs-site.xml

Option 2: Per-Mount Configuration (Flexible)

For more complex scenarios, such as connecting to multiple S3 buckets with different credentials, you can specify configuration properties as options during the mount command.

# Mount an AWS S3 bucket with specific credentials
bin/alluxio mount add --path /s3-images/ --ufs-uri s3://bucket-a/images/ \
  --option s3a.accessKeyId=<AWS_ACCESS_KEY> \
  --option s3a.secretKey=<AWS_SECRET_KEY>

# Mount a different bucket (e.g., MinIO) with different credentials and endpoint
bin/alluxio mount add --path /minio-tables/ --ufs-uri s3://bucket-b/tables/ \
  --option s3a.accessKeyId=<MINIO_ACCESS_KEY> \
  --option s3a.secretKey=<MINIO_SECRET_KEY> \
  --option alluxio.underfs.s3.endpoint=http://minio.internal:9000

Note: Per-mount options take precedence over global settings in alluxio-site.properties. To update options for an existing mount, you must remove and re-add it.

Rules for Mounting

When defining your namespace, you must follow two important 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.

Examples:

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.

Example Scenario:

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.