OCI OKE

本页介绍在已有的 Oracle Cloud Infrastructure Kubernetes Engine (OKE) 集群上部署 Alluxio 时，与 OCI 相关的差异。通用的 Operator 与集群安装流程见 Kubernetes 安装。

概览

OKE 上部署 Alluxio 相较通用 Kubernetes 安装，有三处差异：

• 镜像仓库。镜像推送到 OCI Container Registry (OCIR)。OCIR 使用 Auth Token 鉴权——与其他所有 OCI CLI 调用使用的 API Key 不同。

• Worker 存储。通用型 OCI 机型（例如 VM.Standard.E5.Flex）在系统和容器运行时之后，启动盘只剩 ~36 GiB 可用，所以 page store 使用 emptyDir（或默认的 hostPath），容量 cap 在 ~30 GiB。DenseIO 机型有本地 NVMe，可把 hostPath 指向 NVMe 挂载点，容量更大且 Pod 重启后缓存保留。多 Worker 部署不能用 oci-bv PVC——单个 RWO 卷无法被多个副本共享。

• Load Balancer 注解。OCI Service LB 默认是公网；需要 OCI 专用注解在 Kubernetes Service 上启用内部 LB。

OCI Object Storage 作为 UFS 的挂载在 S3 兼容存储 → Oracle Cloud Infrastructure (OCI) object storage 中已有说明，本页不再重复。Alluxio EE 不支持 oci:// scheme——OCI Object Storage 必须通过 S3 兼容端点挂载。

下文示例全部使用 us-phoenix-1（OCIR 别名 phx.ocir.io）。请根据您订阅的区域调整。

开始之前

下列检查是附加于 通用 Kubernetes 先决条件之上的 OCI 专项。OKE 集群本身的开通不在本页范围内，请参考 OKE 官方文档。

• OKE 集群可达：

  kubectl cluster-info
  kubectl get nodes

• oci-bv StorageClass 存在（新版 OKE 集群默认已安装）：

  kubectl get storageclass oci-bv

• CLI 工具已安装：

  brew install oci-cli kubectl helm skopeo jq          # macOS；Linux 自行调整

• OCI API Key 已配置：

  oci setup config
  oci iam user get --user-id "$OCI_USER_OCID"          # 必须成功

• OCIR Auth Token 已生成（OCI Console → User → Auth Tokens——与 API Key 不是同一个凭证）

• Alluxio 软件包已备齐： Operator 镜像 .tar、Alluxio 镜像 .tar、Helm Chart .tgz、License

解除 passphrase 保护的 API Key。如果 oci setup config 给私钥加了 passphrase，CLI 每次调用都会交互式询问，无法用于自动化：

openssl rsa -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key.pem.dec
mv  ~/.oci/oci_api_key.pem.dec ~/.oci/oci_api_key.pem
chmod 600 ~/.oci/oci_api_key.pem

环境变量

export OCI_REGION=us-phoenix-1
export OCIR_HOST=phx.ocir.io                          # 区域别名；见 OCIR 文档
export OCI_TENANCY_OCID=ocid1.tenancy.oc1..xxxx
export OCI_USER_OCID=ocid1.user.oc1..xxxx
export OCI_OCIR_NAMESPACE=$(oci os ns get --region "$OCI_REGION" --query 'data' --raw-output)

export ALLUXIO_IMAGE_REPO="${OCIR_HOST}/${OCI_OCIR_NAMESPACE}/alluxio-ee"
export ALLUXIO_IMAGE_TAG=AI-3.9-16.0.0

export OCIR_AUTH_TOKEN='<auth-token-from-console>'

安装步骤

1. 推送 Alluxio 镜像到 OCIR

OCIR 不接受 API Key 作为推送凭证。必须使用 Auth Token。~/.oci/config 中的 API Key 用于其他所有 OCI CLI 调用，但不能用于 OCIR 镜像推送。

拼接 OCIR 登录信息并用 skopeo 推送（无需本地 Docker daemon）：

OCIR_USER=$(oci iam user get --user-id "$OCI_USER_OCID" --query 'data.name' --raw-output)
OCIR_LOGIN="${OCI_OCIR_NAMESPACE}/${OCIR_USER}"

echo "$OCIR_AUTH_TOKEN" | skopeo login "$OCIR_HOST" -u "$OCIR_LOGIN" --password-stdin

# Alluxio 镜像
skopeo copy \
  --dest-tls-verify=true \
  "docker-archive:alluxio-enterprise-AI-3.9-16.0.0-linux-amd64-docker.tar" \
  "docker://${ALLUXIO_IMAGE_REPO}:${ALLUXIO_IMAGE_TAG}"

# Operator 镜像
skopeo copy \
  --dest-tls-verify=true \
  "docker-archive:alluxio-operator-3.6.1-linux-amd64-docker.tar" \
  "docker://${OCIR_HOST}/${OCI_OCIR_NAMESPACE}/alluxio-operator:3.6.1"

如果 OCI 账号启用了 Identity Domain（联邦身份），登录用户名为 <namespace>/oracleidentitycloudservice/<user-email>。

✅ 成功： 两个镜像出现在 OCI Console → Developer Services → Container Registry。

2. 创建 ImagePull Secret

每个从 OCIR 拉取镜像的 Pod 都需要一个 docker-registry Secret。在每个需要拉取镜像的命名空间下创建：

kubectl create namespace alx-ns
kubectl -n alx-ns create secret docker-registry ocir-pull \
  --docker-server="$OCIR_HOST" \
  --docker-username="$OCIR_LOGIN" \
  --docker-password="$OCIR_AUTH_TOKEN"

kubectl create namespace alluxio-operator
kubectl -n alluxio-operator create secret docker-registry ocir-pull \
  --docker-server="$OCIR_HOST" \
  --docker-username="$OCIR_LOGIN" \
  --docker-password="$OCIR_AUTH_TOKEN"

3. 使用 OCI 专用值部署 Alluxio

此后按通用的 Kubernetes 安装 指南，从 Step 1 — Prepare Helm Chart 开始。上面的第 1 节替代了通用指南的 Step 0（把镜像推送到私有仓库）。

编写 alluxio-operator.yaml 和 alluxio-cluster.yaml 时请应用下面的 OCI 专用配置。

Operator 配置（alluxio-operator.yaml）：

global:
  image: phx.ocir.io/<OCIR_NAMESPACE>/alluxio-operator
  imageTag: 3.6.1
  imagePullSecrets:
    - ocir-pull

Cluster 镜像与 pull secret（alluxio-cluster.yaml）：

spec:
  image: phx.ocir.io/<OCIR_NAMESPACE>/alluxio-ee
  imageTag: AI-3.9-16.0.0
  imagePullSecrets:
    - ocir-pull

Worker page store——先规划节点本地存储，再把 hostPath 指向它。

Alluxio Worker 的缓存容量受限于每个 Worker Pod 可用的节点本地存储。OKE 上，在设置 pagestore 大小之前，先从以下方案中选一种进行节点存储规划：

• DenseIO 机型（BM.DenseIO.E5、VM.DenseIO2 等）自带高带宽本地 NVMe，是生产级 ML 工作负载的推荐机型。把 NVMe 挂载到节点的 /mnt/alluxio/pagestore，使用默认的 hostPath page store。

• 通用型机型 + 扩大启动盘（VM.Standard.E5.Flex 在创建 Node Pool 时把 bootVolumeSizeInGBs 调大，例如 500–2000 GiB）。启动盘扩容后，hostPath 就有足够空间承载实际工作集。

• 通用型机型 + 每节点挂一块块存储卷——用 Terraform、cloud-init 或 DaemonSet 为每个 Worker 节点额外挂一块 OCI Block Volume，格式化后挂载到 /mnt/alluxio/pagestore，再用 hostPath。每个节点独占自己的卷，不存在 RWO 共享问题。

然后把 page store 大小设成上面规划的容量：

spec:
  worker:
    count: 3
    pagestore:
      # hostPath 是默认，对应节点的 /mnt/alluxio/pagestore。
      # size 请匹配上面规划的存储容量。
      size: 500Gi
      reservedSize: 50Gi

不要使用 pagestore.type: persistentVolumeClaim + oci-bv。oci-bv 是 ReadWriteOnce StorageClass；Alluxio Chart 会把所有 Worker 副本指向同一个 PVC，只有一个副本能 mount 成功，其余 Pending。请使用节点本地存储（hostPath 或 emptyDir）。

评估用简化方案。 OKE 默认的 E5.Flex 启动盘为 ~46 GiB（可用 ~36 GiB）。如果只是评估阶段，可接受小而短暂的缓存，可直接用 pagestore.type: emptyDir + size: 30Gi，无需额外存储规划。不适合生产——每次 Pod 重启缓存都从 UFS 重建。

S3 Gateway 使用内部 Load Balancer。OCI Service LB 默认为公网；把服务流量保持在 VCN 内部：

spec:
  gateway:
    service:
      type: LoadBalancer
      annotations:
        oci.oraclecloud.com/load-balancer-type: "lb"
        service.beta.kubernetes.io/oci-load-balancer-internal: "true"

helm upgrade --install 完成后，OCI 大约 60–90 秒后完成 LB 开通。查看其内部 IP：

kubectl -n alx-ns get svc alluxio-cluster-s3gateway \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

4. 访问集群

步骤 3 创建的 Service LB 位于 VCN 内部。两种常见访问方式：

方案 A —— 从管理员工作站 kubectl port-forward：

kubectl -n alx-ns port-forward svc/alluxio-cluster-s3gateway 39999:39999
aws s3 --endpoint-url http://localhost:39999 ls s3://<bucket>/

kubectl -n alx-ns port-forward svc/alluxio-cluster-coordinator 19999:19999
# 访问 http://localhost:19999 打开 Alluxio Web UI

方案 B —— 通过 VCN 内的 Bastion VM 建立 SSH 隧道：

ssh -f -N -L 39999:<s3gw-internal-lb-ip>:39999 ubuntu@<bastion-ip>
ssh -f -N -L 3000:<grafana-internal-lb-ip>:80 ubuntu@<bastion-ip>

方案 A 无需额外 VM；方案 B 为团队提供可复用的 URL。

卸载

按通用的 Kubernetes 安装 → 卸载 流程完成后，再清除 OCIR ImagePull Secret：

kubectl -n alx-ns delete secret ocir-pull
kubectl -n alluxio-operator delete secret ocir-pull

OCI 基础设施（VCN、OKE 集群、Node Pool）单独管理——清理请参考 OKE 官方文档。推到 OCIR 的 Alluxio 镜像可保留——下次部署可直接复用。

故障排查

现象：OCIR skopeo login 或 push 返回 unauthorized

可能原因： 使用的是 API Key 口令而非 Auth Token。

修复： 在 OCI Console → User → Auth Tokens 生成 Auth Token，导出为 OCIR_AUTH_TOKEN 后重新 skopeo login。API Key 可用于 oci CLI 调用，但不能用于 OCIR 镜像推送。

现象：OCIR 登录成功，但 skopeo copy 报 denied: requested access to the resource is denied

可能原因： 用户账号没有目标 compartment 的 manage repos 权限，或仓库路径错误。

诊断：

oci iam compartment list --compartment-id "$OCI_TENANCY_OCID" --query 'data[].name'

确认目标 compartment，然后检查该用户所在 group 的 IAM 策略是否包含 Allow group <g> to manage repos in compartment <c>。

修复： 授予该策略，或推送到您有权限的 compartment。OCIR 仓库名区分大小写。

现象：OCIR 用户名被拒绝

可能原因： 联邦账号的登录格式错误，Identity Domain tenancy 需要额外一段路径。

修复： 非联邦用户使用 <namespace>/<user-email>。启用 Identity Domain（联邦）时使用 <namespace>/oracleidentitycloudservice/<user-email>。

现象：Worker Pod Pending，PVC 也卡在 Pending

可能原因： 没有 oci-bv StorageClass，或 OKE 版本过旧未包含 OCI Block Volume CSI Driver。

诊断：

kubectl get storageclass
kubectl get pods -n kube-system -l app.kubernetes.io/name=oci-csi-node

修复： 为您的 OKE 集群安装或启用 OCI Block Volume CSI Add-on。详见 OKE Block Volume CSI 文档。

现象：Worker Pod CrashLoopBackOff，日志报 "quota exceeds total disk space"

可能原因： pagestore.size 超过了 Worker Pod 可用的节点本地存储。OKE 默认启动盘 ~46 GiB（可用 ~36 GiB），任何超过 ~36 GiB 的 pagestore.size 都会失败。

修复： 按 §3 规划更大的节点本地存储——扩大 Node Pool 的 bootVolumeSizeInGBs、挂接独立 Block Volume，或切换到 DenseIO 机型——再把 pagestore.size 设为该容量（reservedSize 留 10% 余量）。评估场景下可把 pagestore.size cap 在 30 GiB，使用默认启动盘。

现象：只有一个 Worker 启动，其他 Worker 卡在 Pending 并报 Multi-Attach error for volume

可能原因： pagestore.type: persistentVolumeClaim 配合 oci-bv 这种 RWO StorageClass。Worker 副本共享同一个卷，OCI 只允许一个节点挂载。

修复： 改用 pagestore.type: emptyDir（见 §3）。OKE 上块存储设备一般没有 RWX 能力。

现象：内置 etcd Pod 卡在 ImagePullBackOff

可能原因： Helm chart 自带的 etcd 镜像拉不到。最近的常见情况：docker.io/bitnami/etcd 镜像被下架，导致 Alluxio chart 默认路径不工作。

诊断：

kubectl -n alx-ns describe pod alluxio-cluster-etcd-0 | grep -A3 Events

查找 manifest unknown 或 repository does not exist。

修复： 改用外部 etcd 集群，禁用内置 etcd 并显式指定 endpoint——详见 Kubernetes 安装 — B.3. 使用外部 ETCD。

现象：UFS 写入 OCI Object Storage 返回 HTTP 501 "AWS chunked encoding not supported"

可能原因： OCI 的 S3 兼容 API 不支持 AWS SDK v2 的 chunked transfer encoding，而 Alluxio 默认使用 SDK v2。

修复： UFS 挂载时设置 alluxio.underfs.s3.sdk.version=1。完整的属性清单见 S3 兼容存储 → Oracle Cloud Infrastructure (OCI) object storage。

现象：S3 Gateway Service 的 EXTERNAL-IP 长时间 <pending>

可能原因： OKE 集群创建时没有指定 service-lb-subnet，或该子网 IP 耗尽。

诊断：

kubectl -n alx-ns describe svc alluxio-cluster-s3gateway | grep -A2 Events

查找与子网或 NSG 相关的 OCI LB 开通错误。

修复： 确保集群的 Service LB 子网有空闲 IP，并放通 Gateway 端口。如需更换 Service LB 子网，需重建 OKE 集群，指定 --service-lb-subnet-ids。

相关文档

• Kubernetes 安装 —— 通用的 Operator 和集群安装步骤

• S3 兼容存储 —— 通过 S3 兼容 API 挂载 OCI Object Storage

• 先决条件 —— 硬件、网络端口、资源规格和 etcd 要求

• Worker 配置 —— Page store 容量规划、JVM 调优和存储布局