底层存储

Alluxio 连接到各种各样的存储系统，称为底层文件系统 (UFS)，并通过统一的虚拟命名空间对外暴露。本节介绍 Alluxio 挂载的工作原理，并提供各支持存储系统的配置指南。

挂载工作原理

挂载将一个 Alluxio 虚拟路径绑定到一个 UFS URI。例如，将 s3://my-bucket/data/ 挂载到 /data，即可通过 Alluxio 命名空间中的 /data 访问该存储桶内容。数据不会被复制，读写操作均由 Alluxio 代理转发到底层存储。

关键行为：

可同时在不同路径下挂载多个存储系统。
单挂载选项（通过 mountOptions 或 --option 设置）优先于 AlluxioCluster spec.properties 或 alluxio-site.properties 中设置的全局属性。
挂载点必须位于 Alluxio 命名空间的顶层，不允许嵌套。完整规则请参阅挂载规则。

挂载规则

在定义命名空间时，您必须遵循两个规则，以确保挂载表有效且无歧义。

规则 1：挂载必须是根目录（`/`）的直接子级

您只能在 Alluxio 命名空间的顶层创建挂载点。您不能挂载到根路径（/）本身，也不能在不存在的目录中创建挂载点。

操作

Alluxio 路径

UFS 路径

有效？

原因

挂载存储桶

/s3-data

s3://my-bucket/

✔️ 是

挂载点是根目录的直接子级。

挂载到根目录

/

s3://my-bucket/

❌ 否

根路径不能是挂载点。

挂载到子路径

/data/images

s3://my-bucket/images/

❌ 否

挂载点不能在子目录中创建。

规则 2：挂载不能嵌套

一个挂载点不能创建在另一个挂载点内部，无论是在 Alluxio 命名空间还是在 UFS 命名空间中。例如，如果 /data 挂载到 s3://my-bucket/data，您不能在 /data/tables 创建新挂载（嵌套的 Alluxio 路径），也不能将另一个 UFS 挂载到 s3://my-bucket/data/tables（嵌套的 UFS 路径）。

假设您有一个现有的挂载点：

Alluxio 路径： /data
UFS 路径： s3://my-bucket/data

以下新挂载将是无效的：

新 Alluxio 路径

新 UFS 路径

有效？

拒绝原因

/data/tables

hdfs://namenode/tables

❌ 否

Alluxio 路径 /data/tables 嵌套在现有的 /data 挂载中。

/tables

s3://my-bucket/data/tables

❌ 否

UFS 路径 s3://.../data/tables 嵌套在现有的 s3://.../data 挂载中。

基本挂载配置

每个挂载定义为一个 UnderFileSystem 自定义资源。无论 UFS 类型如何，字段结构相同：

apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: my-mount               # 此挂载资源的唯一名称
  namespace: alx-ns            # 必须与 AlluxioCluster 的命名空间一致
spec:
  alluxioCluster: alluxio-cluster   # 要关联的 AlluxioCluster CR 名称
  path: <UFS_URI>              # UFS URI，例如 s3://bucket/prefix/ 或 gs://bucket/path/
  mountPath: /data             # 此 UFS 在 Alluxio 命名空间中的挂载路径
  mountOptions:                # UFS 特定的连接和凭据属性
    <property-key>: "<value>"

应用并验证：

kubectl apply -f ufs.yaml
kubectl exec -n alx-ns alluxio-cluster-coordinator-0 -- alluxio mount list

path 和 mountOptions 中 UFS 特定的值请参阅对应存储系统的指南。

使用 alluxio mount add 创建挂载点，通过 --option 传入 UFS 特定的连接属性：

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

验证挂载是否生效：

bin/alluxio mount list

各存储系统的 URI scheme 和属性名称请参阅对应指南。

挂载多个存储桶

每个存储位置需要创建一个独立的挂载，且每个挂载必须指定唯一的 mountPath。挂载数量没有硬性上限。

每个位置创建一个 UnderFileSystem CR（mountOptions 属性见各 UFS 指南），然后一起应用：

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

每个位置执行一次 alluxio mount add：

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>

mountOptions 中的单挂载凭据优先于全局凭据，适用于跨账号或跨项目的挂载场景。

Kubernetes：凭据管理

避免将凭据直接写入 UnderFileSystem CR 的 mountOptions——它们会出现在受版本控制的 YAML 中，且每个挂载都需重复填写。以下两种方式可在集群级别统一设置凭据：

方式 A：在 AlluxioCluster CR 的 spec.properties 中设置

全局设置 UFS 凭据属性。各挂载在未指定自身凭据时继承这些属性，单挂载的 mountOptions 仍可覆盖全局设置：

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  properties:
    # UFS 特定的属性名称因类型而异 — 详见各 UFS 指南
    <credential-property-key>: "<credential-value>"

方式 B：Kubernetes Secret + Pod 环境变量

将凭据存储在 Secret 中以避免提交到版本控制，然后以环境变量形式注入到 UFS 驱动读取：

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 特定 — 详见各 UFS 指南
        valueFrom:
          secretKeyRef:
            name: ufs-credentials
            key: credential-value
  worker:
    env:
      - name: <ENV_VAR_NAME>
        valueFrom:
          secretKeyRef:
            name: ufs-credentials
            key: credential-value

包含 S3 特定属性和环境变量名称的完整示例，请参阅在 Kubernetes 中设置凭据。

管理现有挂载

挂载生效后，可用以下命令查看或移除。

列出挂载：

kubectl -n alx-ns get ufs

NAME         PHASE   AGE
alluxio-s3   Ready   13d

移除挂载：

kubectl -n alx-ns delete ufs alluxio-s3

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

挂载表存储在 etcd 中。Alluxio 组件会定期轮询 etcd 以获取最新的挂载表，因此添加和移除会自动在整个集群中传播。

通用对象存储配置

以下配置适用于所有对象存储类型（S3、OSS、BOS、COS、TOS 及 S3 兼容存储）。

请求重试策略

当对象存储返回瞬时错误时，Alluxio 会自动重试请求。以下错误码会触发重试：500、502、503 Slow Down、504。客户端错误（4xx）不会重试。

在 conf/alluxio-site.properties 中或通过挂载选项配置重试行为：

# 每次请求的最大重试次数
alluxio.underfs.business.retry.max.num=10

# 首次重试前的等待时间
alluxio.underfs.business.retry.base.sleep=30ms

# 两次重试之间的最大等待时间（默认值：30s）
alluxio.underfs.business.retry.max.sleep=60s