Ctrlk
ProductsLanguageHome
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Kubernetes 安装

本文档介绍如何通过 Operator 在 Kubernetes 上安装 Alluxio。

概览

制品

您将收到包含三个制品的下载链接：

制品
文件名
用途

Helm chart

alluxio-operator-3.6.1-helmchart.tgz

将 Operator 部署到 Kubernetes

Operator 镜像

alluxio-operator-3.6.1-linux-amd64-docker.tar

Operator pod 的容器镜像

Alluxio 镜像

alluxio-enterprise-AI-3.9-16.0.0-linux-amd64-docker.tar

Alluxio worker 和 coordinator pod 的容器镜像

License

激活集群所必需

版本：以上文件名中的版本字符串仅为示例，您收到的下载链接中包含销售代表为您提供的实际版本。 平台：x86 节点使用 -linux-amd64-docker.tar，ARM 节点使用 -linux-arm64-docker.tar。

Docker 镜像从不从公共镜像仓库拉取 — 它们从 .tar 文件加载后推送至您的私有镜像仓库，再由 Kubernetes 部署。

Helm chart (.tgz)
  └─► 部署 ─► Operator pod  (alluxio-operator image)
                 └─► 监听 AlluxioCluster CRD
                        └─► 创建 ─► Alluxio pods  (alluxio-enterprise image)

Kubernetes 组件

部署的 Alluxio 集群包含以下组件：

  • Operator — 管理 Alluxio 集群的生命周期。每个 Kubernetes 集群安装一次。

  • Coordinator — 处理后台操作（数据加载、释放）。1 个副本。

  • Worker — 缓存数据并通过 S3 API 或 FUSE 提供读取服务。水平扩展以增加缓存容量。

  • ETCD — 服务发现和挂载表存储。建议 3 个副本以实现仲裁。

  • 监控（可选） — Prometheus 和 Grafana。默认启用。

开始之前

在开始之前运行以下检查（约 2 分钟）。跳过此步骤是部署失败最常见的原因。

各组件资源规格（CPU、内存、缓存磁盘）请参阅先决条件 → 资源规格。

EKS 1.23+：内置 EBS 驱动已被移除。请在部署 Alluxio 之前安装 AWS EBS CSI driver 插件，否则 etcd PVC 将持续处于 Pending 状态且没有明确的错误提示。

安装步骤

0. 将 Alluxio 镜像推送至私有镜像仓库

跳过此步骤：如果 Alluxio 镜像已存在于您的私有镜像仓库中，可跳过此步骤。

Alluxio 镜像以 .tar 文件方式交付，必须先加载并推送至私有镜像仓库，Helm chart 才能部署它们。

将镜像加载至本地 Docker：

✅ 成功标志： docker images 显示两个镜像：

重新打标签并推送至私有镜像仓库：

✅ 成功标志： 两个镜像现已推送至私有镜像仓库。请记下完整的镜像路径，后续步骤 1 和步骤 4 中将用到。

如果您的 Kubernetes 集群也无法访问公共镜像仓库（离线环境），第三方镜像（etcd、CSI）也需要迁移。请参阅附录 A：离线部署。

1. 准备 Helm Chart

解压 Helm chart：

在 chart 目录外创建 alluxio-operator.yaml，指定私有镜像仓库中的 Operator 镜像：

2. 创建命名空间

3. 部署 Operator

✅ 成功标志： Helm 命令完成后立即打印 STATUS: deployed：

然后验证所有 pod 正在运行：

✅ 成功标志： 所有 Operator pod 显示 READY 1/1 或 2/2，STATUS = Running，且 RESTARTS = 0。

示例输出如下：

如果 etcd 或 CSI 镜像拉取失败，请参阅附录 A：离线部署。

4. 部署集群

部署前先配置 Hash Ring。 Hash Ring 决定数据如何在 Worker 间分布。部署后修改是破坏性操作——所有缓存数据将丢失。如果您的集群有异构 Worker 或特定容量需求，请在执行下方命令前先查阅附录 B：Hash Ring 处理。

创建一个最小化的 alluxio-cluster.yaml：

部署：

✅ 成功标志： 启动通常需要 2–3 分钟。如果需要从仓库拉取 Alluxio 镜像（约 1.8 GB），首次部署可能耗时更长。实时查看进度：

所有 pod 运行后，kubectl -n alx-ns get alluxiocluster 显示 CLUSTERPHASE = Ready

且 kubectl -n alx-ns get pod 显示所有 pod 变为 Ready 且 STATUS = Running。

如果任何组件无法启动，请参阅附录 D：故障排除。

如需访问 Grafana 仪表盘并导入 Alluxio 仪表盘模板，请参阅监控。

5. 挂载存储

创建 ufs.yaml（S3 示例；其他存储系统请参阅底层存储）：

应用：

✅ 成功标志： kubectl -n alx-ns get ufs 显示 PHASE = Ready。

示例输出：

6. 验证集群

✅ 成功标志： 输出显示您的挂载点（例如 s3://my-bucket/... on /s3/）。

示例输出：

7. 验证数据访问

✅ 成功标志： 返回目录列表且没有错误。

下一步：把你的应用接入集群，选择一种访问方式：

卸载

要从集群中移除 Alluxio 部署，请按顺序运行以下命令：

1. 删除 UFS 挂载和集群：

2. 卸载 Operator：

3. 删除命名空间：

✅ 成功标志： kubectl get namespace 不再显示 alx-ns 或 alluxio-operator，且 kubectl get alluxiocluster -A 返回 No resources found。

下一步：生产部署配置

上述配置适用于评估。生产部署（节点固定、资源调优、持久化 metastore、许可证、哈希环部署前配置、异构 Worker 等）请参阅 生产部署配置。

附录

使用下表查找与您的场景相关的附录章节：

场景
章节

离线环境（集群无法访问公共镜像仓库）

A. 离线部署、B.5. 配置镜像拉取密钥

外部或自定义 ETCD

B.3. 外部 ETCD、B.4. 自定义 ETCD

生产许可证

C. 许可证管理

出现问题

D. 故障排除

A. 离线部署

预检：验证节点到镜像仓库的连通性

部署前，先验证 worker 节点能否从私有镜像仓库拉取镜像。提前发现问题可以避免部署中途出现 ImagePullBackOff。

SSH 登录每个 worker 节点，执行：

crictl 在运行 containerd 或 CRI-O 的节点上均已预装。若拉取失败，请先解决节点的镜像仓库连通性或认证问题，再继续部署。

症状：部署后出现 ImagePullBackOff

症状：部署 Operator 或集群后，部分 pod 卡在 ImagePullBackOff 状态。您的 Kubernetes 集群无法访问公共镜像仓库拉取第三方组件镜像（CSI、etcd、监控）。

Alluxio 镜像已在准备步骤中推送至私有镜像仓库。需要迁移的其余镜像取决于您的具体 Operator 版本。通过检查卡住的 pod 来识别它们：

对每个无法拉取的镜像：在有公网访问权限的机器上拉取，为私有镜像仓库重新打标签并推送。然后更新 alluxio-operator.yaml 或 alluxio-cluster.yaml，将该组件指向您的私有镜像仓库。

CSI 镜像（属于 Operator）可在 alluxio-operator.yaml 中覆盖：

etcd 镜像（属于集群）可在 alluxio-cluster.yaml 中覆盖：

B. 高级配置

本节介绍适应不同场景的常见配置。

B.1. 配置 Alluxio 属性

要修改 Alluxio 的配置，请编辑 alluxio-cluster.yaml 文件中的 .spec.properties 字段。这些属性会附加到 Alluxio pod 内的 alluxio-site.properties 文件中。

B.2. 挂载自定义 ConfigMap 或 Secret

您可以将自定义的 ConfigMap 或 Secret 文件挂载到您的 Alluxio pod 中。这对于提供像 core-site.xml 这样的配置文件或凭据很有用。

示例：挂载一个 Secret

  1. 从本地文件创建 Secret：

  2. 在 alluxio-cluster.yaml 中指定要加载的 Secret 和挂载路径：

    文件 my-file 将在 pod 的 /opt/alluxio/secret/my-file 路径下可用。

B.3. 使用外部 ETCD

让集群使用你自己运维的 etcd，而不是 Operator 部署的那套——见 etcd 管理。 已有状态的集群请走迁移流程，不要直接改指向： 迁移到另一套 etcd。

B.4. 自定义 ETCD 配置

spec.etcd 下的字段遵循 Bitnami etcd Helm chart——见 etcd 管理。

B.5. 配置镜像拉取 Secret

如果您的容器镜像存储在需要身份验证的私有仓库中，您需要创建一个 Kubernetes Secret 来存储您的仓库凭据。

此 Secret 必须在您计划安装 Alluxio 的命名空间中创建。

C. 许可证管理

Alluxio 需要由 Alluxio 销售代表提供的许可证。许可证有两种类型：

  • 集群许可证 — 作用范围为单个集群，通过 alluxio-cluster.yaml 中的 alluxio.license 属性内联设置。适用于评估环境和单集群生产部署。

  • 部署许可证 — 覆盖多个集群，每个集群在许可证内拥有各自独立的容量约束。通过单独的 License Kubernetes 资源应用。适用于管理多个 Alluxio 集群的场景。

C.1. 集群许可证

在 alluxio-cluster.yaml 中直接填入许可证字符串：

C.2. 部署许可证

部署许可证以独立的 License Kubernetes 资源方式应用，可覆盖多个集群。各集群的缓存容量依据部署许可证中为其各自定义的约束条件独立计算——并非共享总配额。

步骤 1：不携带许可证部署集群

按主指南步骤 5 部署 Alluxio 集群，但在 alluxio-cluster.yaml 中省略 alluxio.license 属性。Pod 将启动，但保持 Init 状态直到许可证被应用。

步骤 2：应用许可证

创建 alluxio-license.yaml。clusters 列表中的 name 和 namespace 必须与 AlluxioCluster 的 metadata 完全匹配。

Pod 检测到许可证后将转换为 Running 状态。

clusters 字段中只能列出已在运行的集群。如果 Operator 找不到列出的某个集群，列表中所有集群的许可证操作都将失败。

C.3. 更新部署许可证

要更新现有的部署许可证，请更新 alluxio-license.yaml 中的 licenseString 并重新应用它：

C.4. 检查许可证状态

您可以从 Alluxio Coordinator pod 内部检查许可证详细信息和使用情况。

D. 故障排除

D.1. ETCD pod 卡在 pending 状态

如果 etcd pod 处于 Pending 状态，通常是由于存储问题。使用 kubectl describe pod <etcd-pod-name> 检查事件。

症状：事件消息显示 pod has unbound immediate PersistentVolumeClaims。

原因：PVC 未设置 storageClass，或没有可用的 PV。

解决方案：在 alluxio-cluster.yaml 中指定一个 storageClass：

然后，在重新创建集群之前删除旧的集群和 PVC。

症状：事件消息显示 waiting for first consumer。

原因：storageClass 不支持动态配置，卷必须由管理员手动创建。

解决方案：要么使用动态配置程序，要么手动创建一个满足声明的 PersistentVolume。

D.2. etcd pod 因反亲和性卡在 Pending（节点数少于 3）

现象：etcd pod 处于 Pending 状态，事件消息为 0/N nodes are available: N node(s) didn't match pod anti-affinity rules。

原因：Operator 为 etcd 配置了基于主机名的 requiredDuringSchedulingIgnoredDuringExecution 反亲和性。默认 etcd.replicaCount: 3 需要 3 个不同的节点。若集群节点数少于 3，etcd pod 无法完成调度。

解决方案：对于节点数少于 3 的开发/测试集群，减小副本数：

不要在生产环境中使用 replicaCount: 1——单节点 etcd 没有法定人数，不具备容错能力。

D.3. alluxio-cluster-fuse PVC 处于 pending 状态

alluxio-cluster-fuse PVC 保持在 Pending 状态是正常的。一旦客户端应用程序 pod 开始使用它，它将自动绑定到一个卷并变为 Bound。

D.4. Worker pod 卡在 CrashLoopBackOff

症状：Worker pod 反复崩溃并重启。

首先检查 Worker 日志：

常见原因包括：

  • Pagestore 配额超出磁盘空间 — 日志显示 quota (NNN) exceeds the total disk space。云提供商通常以 GB（十进制）报告磁盘大小，而 Kubernetes 将 Gi 解释为 GiB（二进制）。修复：将 pagestore.size 减少到实际可用空间的约 90%（通过 df -h /mnt/alluxio 检查），将 reservedSize 设置为 size 的约 10%。

  • 许可证过期或无效 — 日志显示许可证错误。修复：应用新许可证。请参阅附录 C：许可证管理。

  • OOM 终止 — 日志显示 Exit Code 137 或 OutOfMemoryError。修复：增加容器内存限制并调整 -Xmx / -XX:MaxDirectMemorySize。请参阅 D.2. 资源和 JVM 调优。

D.5. 首次更新 CR 时 etcd pod 重启

症状：安装完成后第一次 kubectl apply 修改 alluxio-cluster.yaml（即使改动与 etcd 无关），etcd pod 会逐个重启。

原因：Bitnami etcd chart 在初始化新集群时使用 ETCD_INITIAL_CLUSTER_STATE=new，并在第一次 helm upgrade 时将其改为 existing；而 Operator 应用 AlluxioCluster 自定义资源（CR）的任何变更都是通过 helm upgrade 完成的。该变量位于 etcd StatefulSet 的 pod 模板中，因此 Kubernetes 会以滚动重启的方式应用这一改动。

解决方案：无需处理 — 这是预期行为。使用默认的 etcd.replicaCount: 3 时，pod 逐个重启，全程保持 quorum，不会丢失数据。等待滚动重启完成即可：

只要后续不在 CR 中修改 etcd 相关配置，之后的 CR 更新不会再触发此重启。

使用 etcd.replicaCount: 1 时没有 quorum，重启期间 etcd 会短暂不可用，依赖它的操作（挂载变更、worker 注册）在该窗口内可能失败。

E. 平台特定说明

主安装步骤与平台无关。本节记录了特定 Kubernetes 环境的已知差异。

Amazon EKS

EKS 1.23+ 需要 EBS CSI 驱动：Kubernetes 1.23 移除了内置 EBS 卷驱动。在 EKS 1.23+ 上，需安装 AWS EBS CSI driver 插件，否则即使 StorageClass 有输出，PVC 创建仍会静默失败。

验证：

如果没有输出，说明驱动未安装。

Google GKE

/mnt 路径为只读：GKE 节点的根文件系统为只读。多个 Alluxio 组件默认使用 /mnt/alluxio/ 下的 hostPath，导致 worker pod 启动失败并报错：

解决方法：在 alluxio-cluster.yaml 中将所有 hostPath 重定向到可写的基础目录（例如 /home/alluxio/）：

此外，配置 worker 身份持久化，防止 worker 每次重启后注册为新实例（导致旧 worker 残留为 OFFLINE 状态）。有关其重要性及对哈希环影响的完整说明，请参阅重启 Worker。

kind（本地开发）

镜像加载：kind load docker-image 在处理多平台镜像时可能因 digest 错误而失败。请使用以下替代方式：

获取 kind 容器名称：docker ps | grep kindest。

相关文档

  • Alluxio 工作原理 — 架构概述、一致性哈希和故障转移行为

  • 集群管理 — 部署后运维：扩缩容、哈希环调优、Worker 生命周期和 UFS 挂载管理

  • 监控 — Grafana 访问、仪表盘导入、告警规则和 Datadog 集成

Last updated