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

## Method 1: Connect to NAS via NFS Protocol (Recommended)

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.

```yaml
# 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):**

```bash
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`:**

   ```yaml
   # 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:**

   ```yaml
   # 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:

```bash
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.