Storage Requirements

Drive type

AIStor recommends using flash-based storage (NVMe or SSD) for all workload types at any scale. Workloads that require high performance should prefer NVMe over SSD.

For best performance, use 30+TB drives with NVMe over PCIe 4.0 or 5.0.

Directly attached storage

For best performance, provide AIStor with drives attached directly to each host node as a JBOD array with no RAID or similar management layers. AIStor requires the XFS filesystem for best performance and behavior at scale. Using any other type of backing storage (SAN/NAS, ext4, RAID, LVM) typically results in a reduction in performance, reliability, predictability, and consistency.

For Kubernetes deployments, use a Container Storage Interface (CSI) such as AIStor Volume Manager (DirectPV) designed to manage and provision Persistent Volumes on the same host as the AIStor Server pod. Where possible, configure the CSI to format drives as XFS according to the guidelines provided in this documentation.

Use similar hardware

Ensure all drives in a given AIStor Server pool have the same capacity, make, and model. Mixing drive types typically results in performance degradation, as the slowest or smallest drives in the deployment become a bottleneck regardless of the capabilities of larger or faster drives.

Consistent drive mounting

The AIStor Server process requires that drives maintain their ordering at the mounted position across restarts. Arbitrary migration of a drive with existing AIStor Server data to a new mount position, whether intentional or as the result of OS-level behavior, may result in unexpected behavior including data loss.

For Kubernetes environments, your CSI should provide the necessary guarantees around drive mounting and path preservation across host or pod restarts.

On Linux environments, you must use /etc/fstab or a similar mount control system to mount drives at a consistent path. The following example /etc/fstab uses label-based drive mounting and MinIO’s recommended mount options:

$ nano /etc/fstab

# <file system>        <mount point>    <type>  <options>         <dump>  <pass>
LABEL=AISTORDRIVE1     /mnt/drive-1     xfs     defaults,noatime  0       2
LABEL=AISTORDRIVE2     /mnt/drive-2     xfs     defaults,noatime  0       2
LABEL=AISTORDRIVE3     /mnt/drive-3     xfs     defaults,noatime  0       2
LABEL=AISTORDRIVE4     /mnt/drive-4     xfs     defaults,noatime  0       2

You can use mount -a to mount those drives at those paths during initial setup. The Operating System should otherwise mount these drives as part of the node startup process.

Use label-based mounting rules over UUID-based rules. Label-based rules allow swapping an unhealthy or non-working drive with a replacement drive that has matching labels without modifying any configuration files. UUID-based rules require retrieving the replacement drive UUID and editing the /etc/fstab file to replace mappings with the new drive UUID.

Cloud environment instances which depend on mounted external storage may encounter boot failure if one or more of the remote file mounts return errors or failure. For example, an AWS ECS instance with mounted persistent EBS volumes may not boot with the standard /etc/fstab configuration if one or more EBS volumes fail to mount.

You can set the nofail option to silence error reporting at boot and allow the instance to boot with one or more mount issues.

You should not use this option on systems with locally attached disks, as silencing drive errors prevents both AIStor Server and the OS from responding to those errors in a normal fashion.

XFS configuration and guidance

The following subsections apply to XFS formatted drives.

For Kubernetes deployments, refer to the documentation for your CSI or Persistent Volume type for support in setting these configurations.

Disable XFS retry on error

Disable retry-on-error behavior using the max_retries configuration for the following error classes:

EIO Error when reading or writing
ENOSPC Error no space left on device
default All other errors

The default max_retries setting typically directs the filesystem to retry-on-error indefinitely instead of propagating the error. Each AIStor Server process can handle XFS errors appropriately, such that the retry-on-error behavior at best introduces at most unnecessary latency or performance degradation.

The following script iterates through all drives at the specified mount path and sets the XFS max_retries setting to 0 or "fail immediately on error" for the recommended error classes. The script ignores any drives not mounted, either manually or through /etc/fstab. Modify the /mnt/drive line to match the pattern used for your AIStor Server drives.

#!/bin/bash

for i in $(df -h | grep /mnt/drive | awk '{ print $1 }'); do
      mountPath="$(df -h | grep $i | awk '{ print $6 }')"
      deviceName="$(basename $i)"
      echo "Modifying xfs max_retries and retry_timeout_seconds for drive $i mounted at $mountPath"
      echo 0 > /sys/fs/xfs/$deviceName/error/metadata/EIO/max_retries
      echo 0 > /sys/fs/xfs/$deviceName/error/metadata/ENOSPC/max_retries
      echo 0 > /sys/fs/xfs/$deviceName/error/metadata/default/max_retries
done
exit 0

You must run this script on all AIStor Server hosts and configure the script to re-run on reboot, as Linux Operating Systems do not typically persist these changes. You can use a cron job with the @reboot timing to run the above script whenever the node restarts and ensure all drives have retry-on-error disabled. Use crontab -e to create the following job, modifying the script path to match that on each node:

@reboot /opt/minio/xfs-retry-settings.sh