Network Attached Storage (NAS)

Network Attached Storage (NAS) provides centralized file-level storage over a network. Alluxio can connect to NAS systems, making them available as an Under File System (UFS).

This guide covers two primary methods for connecting Alluxio to a NAS:

  1. Via NFS Protocol (Recommended): Alluxio uses its built-in NFS client to connect directly to the NAS server over the network. This is the recommended method as it avoids the need to manage system-level mounts on each node.

  2. Via Host Path (Local Mount): The NAS volume is mounted onto the local filesystem of each Alluxio node. Alluxio interacts with it as if it were a local directory.

This method uses Alluxio's internal NFS v3 client to connect to the NAS server directly. It does not require mounting the NAS on the host nodes.

Prerequisites

Before you start, ensure you have the following information:

Parameter
Description
Example

<NAS_SERVER_IP>

The IP address of the NAS server.

192.168.1.100

<NAS_EXPORT_PATH>

The absolute path of the exported directory on the NAS server.

/exports/data

<NAS_SERVER_AUTHORITY>

A unique name you define to identify this NAS server within Alluxio.

my-nas-server

1. Configuration and Mounting

You can mount an NFS share using the nas:// UFS scheme.

Mount Options:

Property
Description
Default

fs.nas.ipAddress

(Required) The IP address of the NAS server.

fs.nas.service.version

The NFS protocol version. Currently, only "3" is supported.

"3"

fs.nas.uid

The user ID that Alluxio will use to access files on the NFS share.

"0" (root)

fs.nas.gid

The group ID that Alluxio will use to access files on the NFS share.

"0" (root)

With the Kubernetes Operator:

Create an UnderFileSystem resource with the required mount options.

# ufs.yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-nas-nfs
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: nas://<NAS_SERVER_AUTHORITY>/<NAS_EXPORT_PATH>/
  mountPath: /nas-nfs
  mountOptions:
    fs.nas.ipAddress: <NAS_SERVER_IP>
    fs.nas.uid: "0"
    fs.nas.gid: "0"
    fs.nas.service.version: "3"

With the Command Line (CLI):

bin/alluxio mount add --path /nas \
  --ufs-uri "nas://<NAS_SERVER_AUTHORITY>/<NAS_EXPORT_PATH>/" \
  --option fs.nas.ipAddress=<NAS_SERVER_IP> \
  --option fs.nas.uid=0 \
  --option fs.nas.gid=0 \
  --option fs.nas.service.version=3

Note: When mounting the root of an export, include a trailing slash in the UFS URI (e.g., /exports/data/). The NAS_SERVER_AUTHORITY is a logical name used by Alluxio to distinguish between different NAS mounts and does not need to be a real hostname.

2. Advanced Configuration

You can tune the following parameters in alluxio-site.properties or provide them as mount options (--option key=value) to optimize performance.

Property
Description
Default

alluxio.underfs.nas.inputstream.max.buffer.size

The maximum buffer size for the input stream when reading data from NAS. A larger buffer can improve sequential read performance but consumes more memory.

8MB

alluxio.underfs.nas.liststatus.iterable.max.byte.size.per.response

The maximum size of a single response for a directory listing operation. This helps prevent memory issues when listing directories with a very large number of files.

4MB


Method 2: Mount NAS as a Local Filesystem (Host Path)

In this method, you mount the NAS share to a consistent local path on all Alluxio nodes. Alluxio then mounts this local path.

Prerequisites

  • A NAS server with a share accessible over the network.

  • The NAS share is mounted at the same local path on every Alluxio node (e.g., /mnt/nas-share).

  • You have read/write permissions on this local mount point for the user running the Alluxio processes.

1. Mount the NAS Locally on Nodes

Before configuring Alluxio, you must first mount your NAS share to a local directory on each Alluxio node. The steps to do this depend on your NAS and operating system. Ensure the mount point is identical across all nodes.

2. Mount in Alluxio

Once the NAS is available as a local directory, you can mount it into Alluxio. The UFS URI will use the file:/// scheme.

With the Kubernetes Operator:

If using the Alluxio Operator, you must expose the host path to the Alluxio pods and then create an UnderFileSystem resource.

  1. Expose the host path in AlluxioCluster:

    # alluxio-cluster.yaml
    apiVersion: k8s-operator.alluxio.com/v1
    kind: AlluxioCluster
    spec:
      hostPaths:
        # This makes the node's /mnt/nas-share available inside the pod at /ufs/nas
        worker:
          /mnt/nas-share: /ufs/nas
        coordinator:
          /mnt/nas-share: /ufs/nas
        fuse:
          /mnt/nas-share: /ufs/nas
  2. Create the UnderFileSystem mount:

    # ufs.yaml
    apiVersion: k8s-operator.alluxio.com/v1
    kind: UnderFileSystem
    metadata:
      name: alluxio-nas-local
      namespace: alx-ns
    spec:
      alluxioCluster: alluxio-cluster
      # Path inside the pod
      path: file:///ufs/nas
      # Desired path in Alluxio's namespace
      mountPath: /nas

With the Command Line (CLI):

If the NAS is mounted at /mnt/nas-share on the Alluxio servers, use the following command:

bin/alluxio mount add --path /nas/ --ufs-uri file:///mnt/nas-share

Permissions and Identity

  • Method 1 (NFS Protocol): File permissions are determined by the uid and gid provided in the mount options. Alluxio performs all file operations on the NFS server as this user/group. Ensure the specified uid/gid has the correct permissions on the NFS export.

  • Method 2 (Host Path): File permissions are determined by the user that the Alluxio processes are running as. That user must have the necessary read/write permissions on the local NAS mount point.

Last updated