Home

在 Kubernetes 上安装

本文档介绍如何通过 Operator 在 Kubernetes 上安装 Alluxio，Operator 是一个用于管理应用程序的 Kubernetes 扩展。

安装步骤

1. 准备工作

在开始之前，请确保您已查看资源先决条件和兼容性。

假设所需的容器镜像（包括 Alluxio 和第三方组件）对 Kubernetes 集群是可访问的。如果您的集群无法访问公共镜像仓库，请参阅附录 A：处理镜像获取说明。

首先，下载并解压 operator helm chart：

# The command will extract the files to the directory alluxio-operator/
$ tar zxf alluxio-operator-3.3.2-helmchart.tgz

这将创建包含 Helm chart 的 alluxio-operator 目录。

2. 部署 Alluxio Operator

创建一个 alluxio-operator/alluxio-operator.yaml 文件来指定 operator 镜像。

global:
  image: <PRIVATE_REGISTRY>/alluxio-operator
  imageTag: 3.3.2

现在，使用 Helm 部署 operator：

$ cd alluxio-operator
# The last parameter is the directory to the helm chart; "." means the current directory
$ helm install operator -f alluxio-operator.yaml .

验证 operator pod 是否正在运行：

$ kubectl -n alluxio-operator get pod
NAME                                              READY   STATUS    RESTARTS   AGE
alluxio-cluster-controller-5647cc664d-lrx84       1/1     Running   0          14s
alluxio-collectinfo-controller-667b746fd6-hfzqk   1/1     Running   0          14s
alluxio-csi-controller-7bd66df6cf-7kh6k           2/2     Running   0          14s
alluxio-csi-nodeplugin-9cc9v                      2/2     Running   0          14s
...

如果 operator pod 因镜像拉取错误而无法启动，您的 Kubernetes 集群可能无法访问公共镜像仓库。请参阅附录 A.2：无法访问公共镜像仓库。

3. 部署 Alluxio 集群

对于生产环境，我们建议使用特定的节点选择器和元数据的持久存储来部署 Alluxio 集群。

首先，为您希望运行 Alluxio 协调器和工作节点的 Kubernetes 节点打上标签：

kubectl label nodes <node-name> alluxio-role=coordinator
kubectl label nodes <node-name> alluxio-role=worker

接下来，创建一个 alluxio-cluster.yaml 文件。此示例包括一个集群许可证、用于生产环境的 nodeSelector 和一个持久的 metastore。

集群许可证是开始使用的最简单方法。有关其他选项，包括推荐用于生产的部署许可证，请参阅附录 D：许可证管理。有关更高级的集群配置，请参阅附录 C：高级配置。

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
metadata:
  name: alluxio-cluster
  namespace: alx-ns
spec:
  image: <PRIVATE_REGISTRY>/alluxio-enterprise
  imageTag: AI-3.7-13.0.0
  properties:
    alluxio.license: <YOUR_CLUSTER_LICENSE>
  coordinator:
    nodeSelector:
      alluxio-role: coordinator
    metastore:
      type: persistentVolumeClaim
      storageClass: "gp2"
      size: 4Gi
  worker:
    nodeSelector:
      alluxio-role: worker
    count: 2
    pagestore:
      size: 100Gi

部署 Alluxio 集群：

$ kubectl create namespace alx-ns
$ kubectl create -f alluxio-cluster.yaml

检查集群的状态。所有 pod 变为 Ready 可能需要几分钟时间。

# Check the cluster status
$ kubectl -n alx-ns get alluxiocluster
NAME              CLUSTERPHASE   AGE
alluxio-cluster   Ready          2m18s

# Check the running pods
$ kubectl -n alx-ns get pod
NAME                                          READY   STATUS    RESTARTS   AGE
alluxio-cluster-coordinator-0                 1/1     Running   0          2m3s
alluxio-cluster-etcd-0                        1/1     Running   0          2m3s
...
alluxio-cluster-worker-85fd45db46-c7n9p       1/1     Running   0          2m3s
...

如果任何组件无法启动，请参阅附录 B：故障排除获取指导。

4. 连接到存储

Alluxio 通过连接到各种存储系统（称为底层文件系统，UFS）来统一访问您现有的数据。您可以通过创建 UnderFileSystem 资源来挂载 UFS。

有关支持的存储系统的完整列表，请参阅连接到存储指南。

以下示例展示了如何挂载一个 S3 存储桶。创建一个 ufs.yaml 文件：

apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-s3
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: s3://<S3_BUCKET>/<S3_DIRECTORY>
  mountPath: /s3
  mountOptions:
    s3a.accessKeyId: <S3_ACCESS_KEY_ID>
    s3a.secretKey: <S3_SECRET_KEY>
    alluxio.underfs.s3.region: <S3_REGION>

应用配置以挂载存储：

$ kubectl create -f ufs.yaml

验证挂载状态：

# Verify the UFS resource is ready
$ kubectl -n alx-ns get ufs
NAME         PHASE   AGE
alluxio-s3   Ready   46s
​
# Check the mount table in Alluxio
$ kubectl -n alx-ns exec -it alluxio-cluster-coordinator-0 -- alluxio mount list 2>/dev/null
Listing all mount points
s3://my-bucket/path/to/mount  on  /s3/ properties={...}

5. 访问数据

Alluxio 提供多种 API 供应用程序访问数据。有关一般概述，请参阅访问数据。

  • 通过 FUSE 的 POSIX API：ML/AI 工作负载最常用的方法。将 Alluxio 挂载为本地文件系统。请参阅 FUSE 指南。

  • S3 API：适用于已使用 S3 SDK 的应用程序。请参阅 S3 API 指南。

  • 通过 FSSpec 的 Python API：为数据科学库提供的原生 Pythonic 接口。请参阅 FSSpec 指南。

附录

A. 处理镜像

部署需要两种类型的容器镜像：

  1. Alluxio 镜像：由您的 Alluxio 销售代表提供。

  2. 第三方镜像：用于 etcd 和 CSI 插件等组件，通常从公共仓库拉取。

所有镜像必须对您的 Kubernetes 集群可访问。如果您的集群处于气隙环境或无法访问公共仓库，您必须拉取所有必需的镜像并将其推送到您的私有仓库。

A.1. Alluxio 镜像

主要的 Alluxio 镜像是：

  • alluxio-operator-3.3.2-docker.tar

  • alluxio-enterprise-AI-3.7-13.0.0-docker.tar

加载并推送到您的私有仓库：

# Load the images locally
$ docker load -i alluxio-operator-3.3.2-docker.tar
$ docker load -i alluxio-enterprise-AI-3.7-13.0.0-docker.tar
​
# Retag the images for your private registry
$ docker tag alluxio/operator:3.3.2 <PRIVATE_REGISTRY>/alluxio-operator:3.3.2
$ docker tag alluxio/alluxio-enterprise:AI-3.7-13.0.0 <PRIVATE_REGISTRY>/alluxio-enterprise:AI-3.7-13.0.0
​
# Push to the remote registry
$ docker push <PRIVATE_REGISTRY>/alluxio-operator:3.3.2
$ docker push <PRIVATE_REGISTRY>/alluxio-enterprise:AI-3.7-13.0.0

A.2. 无法访问公共镜像仓库

如果您的集群无法从公共仓库拉取镜像，您会看到 pod 卡在 ContainerCreating 或 ImagePullBackOff 状态。您必须手动拉取、重新标记并将所需的第三方镜像推送到您的私有仓库。

第三方依赖镜像

组件
镜像名称
版本

operator CSI

registry.k8s.io/sig-storage/csi-node-driver-registrar

v2.0.0

operator CSI

registry.k8s.io/sig-storage/csi-provisioner

v2.0.5

cluster ETCD

docker.io/bitnami/etcd

3.5.9-debian-11-r24

cluster ETCD

docker.io/bitnami/os-shell

11-debian-11-r2

cluster monitor

grafana/grafana

10.4.5

cluster monitor

prom/prometheus

v2.52.0

迁移镜像的命令

# Pull the Docker images (specify --platform if needed)
$ docker pull registry.k8s.io/sig-storage/csi-node-driver-registrar:v2.0.0
$ docker pull registry.k8s.io/sig-storage/csi-provisioner:v2.0.5
...

# Tag the images with your private registry
$ docker tag registry.k8s.io/sig-storage/csi-node-driver-registrar:v2.0.0 <PRIVATE_REGISTRY>/csi-node-driver-registrar:v2.0.0
...

# Push the images to your private registry
$ docker push <PRIVATE_REGISTRY>/csi-node-driver-registrar:v2.0.0
...

更新 YAML 文件

更新 alluxio-operator.yaml 和 alluxio-cluster.yaml 以指向您私有仓库中的镜像。

alluxio-operator.yaml 示例：

global:
  image: <PRIVATE_REGISTRY>/alluxio-operator
  imageTag: 3.3.2
alluxio-csi:
  controllerPlugin: 
    provisioner: 
      image: <PRIVATE_REGISTRY>/csi-provisioner:v2.0.5
  nodePlugin: 
    driverRegistrar: 
        image: <PRIVATE_REGISTRY>/csi-node-driver-registrar:v2.0.0

alluxio-cluster.yaml 示例：

spec:
  image: <PRIVATE_REGISTRY>/alluxio-enterprise
  imageTag: AI-3.7-13.0.0
  etcd:
    image:
      registry: <PRIVATE_REGISTRY>
      repository: <PRIVATE_REPOSITORY>/etcd
      tag: 3.5.9-debian-11-r24
...

B. 故障排除

B.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：

spec:
  etcd:
    persistence:
      storageClass: <YOUR_STORAGE_CLASS>
      size: 10Gi # 示例大小

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

症状：事件消息显示 waiting for first consumer。 原因：storageClass 不支持动态配置，卷必须由管理员手动创建。 解决方案：要么使用动态配置程序，要么手动创建一个满足声明的 PersistentVolume。

B.2. alluxio-cluster-fuse PVC 处于 pending 状态

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

C. 高级配置

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

C.1. 配置 Alluxio 属性

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

C.2. 配置哈希环

一致性哈希环决定了数据如何映射到工作节点。在部署集群之前定义哈希环策略至关重要，因为之后更改这些设置是破坏性操作，将导致所有缓存数据丢失。

需要考虑的关键属性，应在 alluxio-cluster.yaml 的 .spec.properties 下设置：

  • 哈希环模式 (alluxio.user.dynamic.consistent.hash.ring.enabled):

    • true (默认): 动态模式。仅包括在线的工作节点。最适合大多数环境。

    • false: 静态模式。包括所有已注册的工作节点，无论其在线还是离线。如果需要稳定的环视图，即使工作节点暂时不可用，也应使用此模式。

  • 虚拟节点 (alluxio.user.worker.selection.policy.consistent.hash.virtual.node.count.per.worker):

    • 默认: 2000。控制负载均衡的粒度。

  • 工作节点容量 (alluxio.user.worker.selection.policy.consistent.hash.provider.impl):

    • DEFAULT (默认): 假定所有工作节点容量相等。

    • CAPACITY: 根据工作节点存储容量分配虚拟节点。用于异构集群。

更多详情，请参阅哈希环管理。

C.3. 资源和 JVM 调优

您可以为每个组件配置资源限制和 JVM 选项。

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  worker:
    count: 2
    resources:
      limits:
        cpu: "12"
        memory: "36Gi"
      requests:
        cpu: "1"
        memory: "32Gi"
    jvmOptions:
      - "-Xmx22g"
      - "-Xms22g"
      - "-XX:MaxDirectMemorySize=10g"
  coordinator:
    resources:
      limits:
        cpu: "12"
        memory: "36Gi"
      requests:
        cpu: "1"
        memory: "32Gi"
    jvmOptions:
      - "-Xmx4g"
      - "-Xms1g"

容器的总内存限制应略大于其堆大小 (-Xmx) 和直接内存大小 (-XX:MaxDirectMemorySize) 的总和，以避免内存不足错误。

C.4. 使用 PVC 作为页面存储

要持久化工作节点的缓存数据，请为页面存储指定一个 PersistentVolumeClaim (PVC)。

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  worker:
    pagestore:
      type: persistentVolumeClaim
      storageClass: "" # 默认为 "standard"，对于静态绑定可以为空
      size: 100Gi
      reservedSize: 10Gi # 建议为缓存大小的 5-10%

C.5. 挂载自定义 ConfigMap 或 Secret

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

示例：挂载一个 Secret

  1. 从本地文件创建 secret：

    kubectl -n alx-ns create secret generic my-secret --from-file=/path/to/my-file

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

    apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  secrets:
    worker:
      my-secret: /opt/alluxio/secret
    coordinator:
      my-secret: /opt/alluxio/secret

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

C.6. 使用外部 ETCD

如果您有外部的 ETCD 集群，您可以配置 Alluxio 使用它，而不是由 operator 部署的那个。

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  etcd:
    enabled: false
  properties:
    alluxio.etcd.endpoints: http://external-etcd:2379
    # If using TLS for ETCD, add the following:
    # alluxio.etcd.tls.enabled: "true"

C.7. 自定义 ETCD 配置

spec.etcd 下的字段遵循 Bitnami ETCD helm chart。例如，要设置 etcd pod 的节点亲和性，可以按照 Kubernetes 文档 中的说明使用 affinity 字段。

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  etcd:
    affinity:
      nodeAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
          nodeSelectorTerms:
          - matchExpressions:
            - key: topology.kubernetes.io/zone
              operator: In
              values:
              - antarctica-east1
              - antarctica-west1

D. 许可证管理

Alluxio 需要您的销售代表提供的许可证。有两种类型：集群许可证（用于单个测试集群）和部署许可证（推荐用于生产）。

D.1. 集群许可证

集群许可证直接在 alluxio-cluster.yaml 文件中设置。不建议在生产环境中使用此方法。

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  properties:
    alluxio.license: <YOUR_CLUSTER_LICENSE>

D.2. 部署许可证

部署许可证是生产环境推荐的方法，可以覆盖多个集群。它通过在创建集群后创建一个单独的 License 资源来应用。

步骤 1：创建没有许可证的集群 如主指南的第 3 步所述部署 Alluxio 集群，但不要在 alluxio-cluster.yaml 中包含 alluxio.license 属性。pod 将启动但保持在 Init 状态，等待许可证。

步骤 2：应用许可证 如主指南的第 4 步所示创建一个 alluxio-license.yaml 文件。此文件中的 name 和 namespace 必须与您的 AlluxioCluster 的元数据匹配。

apiVersion: k8s-operator.alluxio.com/v1
kind: License
metadata:
  name: alluxio-license
  namespace: alx-ns
spec:
  clusters:
  - name: alluxio-cluster
    namespace: alx-ns
  licenseString: <YOUR_DEPLOYMENT_LICENSE>

使用 kubectl create -f alluxio-license.yaml 应用此文件。Alluxio pod 将检测到许可证并转换为 Running 状态。

警告：仅在 clusters 列表中指定正在运行的集群。如果 operator 找不到列出的集群，则所有集群的许可证操作都将失败。

D.3. 更新部署许可证

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

kubectl delete -f alluxio-license.yaml
kubectl create -f alluxio-license.yaml

D.4. 检查许可证状态

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

# Get a shell into the coordinator pod
$ kubectl -n alx-ns exec -it alluxio-cluster-coordinator-0 -- /bin/bash

# View license details (expiration, capacity)
$ alluxio license show

# View current utilization
$ alluxio license status

Last updated