在 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 coordinator 和 worker 的 Kubernetes 节点打上标签。这可以确保 Alluxio pod 被调度到适当的机器上。

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

其次，创建一个 alluxio-cluster.yaml 文件。在部署之前，审查并定义几个关键配置以匹配您的环境需求非常重要：

许可证管理：集群许可证是入门的最简单方法。对于生产环境，建议使用部署许可证。有关两种选项的详细信息，请参阅附录 E：许可证管理。
哈希环配置：在部署之前配置哈希环至关重要，因为后续更改可能是破坏性的。详细指南请参阅附录 B：处理哈希环。
异构集群：如果您的集群包含不同容量的 worker，则必须定义特定的数据分发策略。配置步骤请参阅附录 C：处理异构 Worker。
高级配置：对于其他设置，例如资源调优或使用外部 etcd，请参阅附录 D：高级配置。

以下示例提供了包含 nodeSelector 和持久化 metastore 的基本配置：

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

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

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. 处理镜像

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

Alluxio 镜像：由您的 Alluxio 销售代表提供。
第三方镜像：用于 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. 处理哈希环

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

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

哈希环模式 (alluxio.user.dynamic.consistent.hash.ring.enabled):
- true (默认): 动态模式。仅包括在线的 worker。最适合大多数环境。
- false: 静态模式。包括所有已注册的 worker，无论其在线还是离线。如果需要稳定的环视图，即使 worker 暂时不可用，也应使用此模式。
虚拟节点 (alluxio.user.worker.selection.policy.consistent.hash.virtual.node.count.per.worker):
- 默认: 2000。控制负载均衡的粒度。
Worker 容量 (alluxio.user.worker.selection.policy.consistent.hash.provider.impl):
- DEFAULT (默认): 假定所有 worker 容量相等。
- CAPACITY: 根据 worker 存储容量分配虚拟节点。用于异构集群。

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

C. 处理异构 Worker

Alluxio operator 允许您管理异构 worker 配置，这对于节点具有不同磁盘规格的集群特别有用。此功能使您能够定义不同的 worker 组，每个组都有自己的存储设置。

注意： 虽然这提供了灵活性，但确保每个 worker 组内的一致性至关重要。配置错误可能导致意外错误。本指南涵盖了配置具有不同磁盘设置的 worker 的支持用例。

要设置异构 worker，请按照以下步骤操作：

按规格分组节点：首先，根据磁盘配置识别并分组您的 Kubernetes 节点。例如，您可能有一组10个节点，每个节点有一个1TB的磁盘，另一组12个节点，每个节点有两个800GB的磁盘。

标记节点：为每组节点分配唯一的标签。这使您可以将特定配置应用于正确的机器。

# 为有一个磁盘的节点打标签
$ kubectl label nodes <node-name> apps.alluxio.com/disks=1
# 为有两个磁盘的节点打标签
$ kubectl label nodes <node-name> apps.alluxio.com/disks=2

定义 Worker 组并启用基于容量的哈希：在您的 alluxio-cluster.yaml 中，使用 .spec.workerGroups 字段定义每个组。使用 nodeSelector 将特定配置应用于具有相应标签的节点。

对于异构集群，还建议将哈希环配置为容量感知。这可以确保具有更多存储容量的 worker 分配到成比例的更大数据份额。您可以通过将 alluxio.user.worker.selection.policy.consistent.hash.provider.impl 设置为 CAPACITY 来实现这一点。

以下示例显示了异构集群的完整配置：

apiVersion: k8s-operator.alluxio.com/v1
kind: AlluxioCluster
spec:
  properties:
    alluxio.user.worker.selection.policy.consistent.hash.provider.impl: CAPACITY

  # 所有 worker 的通用配置
  worker:
    resources:
      limits:
        memory: 40Gi
      requests:
        memory: 36Gi
    jvmOptions: ["-Xmx20g", "-Xms20g", "-XX:MaxDirectMemorySize=16g"]
  
  # 为每个 worker 组定义特定配置
  workerGroups:
  - worker:
      count: 10
      nodeSelector:
        apps.alluxio.com/disks: 1
      pagestore:
        hostPath: /mnt/disk1/alluxio/pagestore
        size: 1Ti
  - worker:
      count: 12
      nodeSelector:
        apps.alluxio.com/disks: 2
      pagestore:
        hostPath: /mnt/disk1/alluxio/pagestore,/mnt/disk2/alluxio/pagestore
        size: 800Gi,800Gi

D. 高级配置

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

D.1. 配置 Alluxio 属性

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

D.2. 资源和 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) 的总和，以避免内存不足错误。

D.3. 使用 PVC 作为页面存储

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

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

D.4. 挂载自定义 ConfigMap 或 Secret

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

示例：挂载一个 Secret

从本地文件创建 secret：

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

在 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 路径下可用。

D.5. 使用外部 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"

D.6. 自定义 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

E. 许可证管理

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

E.1. 集群许可证

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

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

E.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 找不到列出的集群，则所有集群的许可证操作都将失败。

E.3. 更新部署许可证

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

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

E.4. 检查许可证状态

您可以从 Alluxio coordinator 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

F. 故障排除

F.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。

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

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

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

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

Last updated 2 months ago