在 Azure Kubernetes 服务 (AKS) 上安装托管的 KubeRay 扩展(预览版)

Important

AKS 预览功能可在自助服务和自愿选择的基础上启用。 预览版按“现状”和“视供应情况”提供,它们不包括在服务级别协议和有限保证范围内。 AKS 预览功能是由客户支持尽最大努力部分覆盖。 因此,这些功能并不适合用于生产。 有关详细信息,请参阅以下支持文章:

Azure Kubernetes 服务 (AKS)的托管 KubeRay 扩展处于预览状态。 它在您的集群上安装和管理 KubeRay Operator 和 Ray 自定义资源定义(CRD):RayCluster、RayJob、RayCronJob和RayService。

本文介绍如何使用Azure CLI安装、验证、更新和删除扩展。 还可以部署示例 Ray 工作负载,以确认 Operator 按预期管理 Ray 资源。

Prerequisites

  • Azure 订阅和 AKS 群集,该群集运行 Kubernetes 1.34 或更高版本,并在 AKS 支持的区域中使用 托管标识。 如果没有群集,请参阅使用 Azure CLI 创建 AKS 群集。
  • Azure CLI的当前版本。
  • k8s-extension Azure CLI扩展版本 1.8.0 或更高版本。
  • kubectl 与群集的 Kubernetes 版本兼容。
  • 注册Azure资源提供程序、管理群集扩展、检索群集凭据和检查 Kubernetes 资源的权限。

Limitations

  • 现有的开源软件 (OSS) KubeRay 安装:在安装托管的 KubeRay 扩展()之前,microsoft.kuberay 安装被拒绝后,仍可能更改 Ray CRD 架构和所有权,删除失败的扩展也不会撤消这些更改。 保留 CRDs 和工作负载资源。 如果安装已失败,请在重试之前按照 恢复指南 操作。

准备好你的环境

以下示例使用 Bash。 设置订阅和现有群集详细信息,然后登录:

SUBSCRIPTION_ID="<subscription-id>"
RESOURCE_GROUP="<existing-resource-group>"
CLUSTER_NAME="<existing-aks-cluster>"
EXTENSION_NAME="kuberay"
RELEASE_TRAIN="preview"

az login
az account set --subscription "$SUBSCRIPTION_ID"

检查群集的 Kubernetes 版本。 在继续之前,确认返回的版本为 1.34 或更高版本:

az aks show \
  --resource-group "$RESOURCE_GROUP" \
  --name "$CLUSTER_NAME" \
  --query kubernetesVersion \
  --output tsv

连接到群集:

az aks get-credentials \
  --resource-group "$RESOURCE_GROUP" \
  --name "$CLUSTER_NAME"

安装或更新 CLI 扩展并注册所需的资源提供程序:

az extension add --name k8s-extension --upgrade

az provider register --namespace Microsoft.ContainerService --wait
az provider register --namespace Microsoft.KubernetesConfiguration --wait

检查已安装的 CLI 扩展版本:

az extension show --name k8s-extension --query version --output tsv

安装 CLI 扩展可提供管理命令;它不会在群集上安装 KubeRay。

卸载现有的 OSS KubeRay Operator

如果没有自托管 Operator,请跳过此步骤。 否则,请备份工作负载数据和清单,暂停 RayCronJob 计划,并等待正在运行的作业完成,然后再删除该 Operator。

对于 Helm 安装,请查找发布名称和命名空间:

helm list --all-namespaces

仅删除 operator 发布并确认其部署已消失:

OSS_RELEASE_NAME="<existing-kuberay-release-name>"
OSS_RELEASE_NAMESPACE="<existing-kuberay-release-namespace>"

helm uninstall "$OSS_RELEASE_NAME" --namespace "$OSS_RELEASE_NAMESPACE"
kubectl get deployments --namespace "$OSS_RELEASE_NAMESPACE"

检查保留的命名空间是否显示 Active,并且每个保留的 *.ray.io CRD 在 ESTABLISHED 列中显示 True:

kubectl get namespace "$OSS_RELEASE_NAMESPACE"
kubectl get crds \
  --output='custom-columns=NAME:.metadata.name,ESTABLISHED:.status.conditions[?(@.type=="Established")].status'

如果命名空间正在终止或未建立 Ray CRD,请在启用扩展之前解决此问题。

对于其他安装方法,请使用其移除流程。 保留 Ray CRD 和工作负荷资源;请勿删除其命名空间或 CRD。

安装托管的 KubeRay 扩展

列出群集可用的扩展版本和 preview 发布序列:

az k8s-extension extension-types list-versions-by-cluster \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --cluster-type managedClusters \
  --extension-type microsoft.kuberay \
  --release-train "$RELEASE_TRAIN" \
  --output table

确认返回的是兼容版本。 如果未返回任何内容,请参阅 扩展版本发现疑难解答。

创建启用了自动升级的扩展。 该命令使用以下值:

  • --extension-type microsoft.kuberay 安装托管的 KubeRay 扩展。
  • --scope cluster 为整个群集安装该扩展。
  • --release-namespace kuberay-system 设置部署的 kuberay-operator 命名空间。
  • --release-train "$RELEASE_TRAIN" 选择 preview 发布序列。
  • --auto-upgrade-minor-version true 启用自动升级。 请勿使用此设置指定 --version。
az k8s-extension create \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --cluster-type managedClusters \
  --name "$EXTENSION_NAME" \
  --extension-type microsoft.kuberay \
  --scope cluster \
  --release-namespace kuberay-system \
  --release-train "$RELEASE_TRAIN" \
  --auto-upgrade-minor-version true

验证扩展安装

检查已安装的版本和预配状态:

az k8s-extension show \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --cluster-type managedClusters \
  --name "$EXTENSION_NAME" \
  --query "{name:name,version:currentVersion,provisioningState:provisioningState,extensionState:extensionState}" \
  --output table

安装最多可能需要 15 分钟。 等待命令输出显示以下值,然后验证操作员部署是否可用,并验证 Ray CRD 已安装:

  • provisioningState 是 Succeeded.
  • extensionState 为 Available 或 Ready.
kubectl wait \
  --for=condition=Available \
  deployment/kuberay-operator \
  --namespace kuberay-system \
  --timeout=5m

kubectl get crds \
  rayclusters.ray.io \
  raycronjobs.ray.io \
  rayjobs.ray.io \
  rayservices.ray.io \
  --output name

如果预配或就绪情况检查失败,请参阅 排查托管 KubeRay 扩展问题。

运行示例 Ray 工作负载

部署一个仅使用 CPU 的 RayCluster,并提交一个 RayJob,以确认 KubeRay operator 可以协调 Ray 资源并运行分布式任务。 此示例使用一个头 Pod 和一个工作 Pod。

设置示例资源名称和 Ray 图像:

RAY_NAMESPACE="kuberay-sample"
RAY_CLUSTER_NAME="sample-raycluster"
RAY_JOB_NAME="sample-rayjob"
RAY_VERSION="2.58.0"
RAY_IMAGE="mcr.azk8s.cn/aks/ai-runtime/ray@sha256:e9a329eef15e5a13d50c3186c2b8036cd3728c6e218da860de23e8494b99ddd3"

创建命名空间并部署 RayCluster:

kubectl create namespace "$RAY_NAMESPACE"

kubectl apply -f - <<YAML
apiVersion: ray.io/v1
kind: RayCluster
metadata:
  name: ${RAY_CLUSTER_NAME}
  namespace: ${RAY_NAMESPACE}
spec:
  rayVersion: "${RAY_VERSION}"
  headGroupSpec:
    rayStartParams:
      num-cpus: "0"
      dashboard-host: "0.0.0.0"
    template:
      spec:
        containers:
        - name: ray-head
          image: ${RAY_IMAGE}
          resources:
            requests:
              cpu: 500m
              memory: 2Gi
            limits:
              cpu: "1"
              memory: 4Gi
  workerGroupSpecs:
  - groupName: cpu-workers
    replicas: 1
    minReplicas: 1
    maxReplicas: 1
    rayStartParams:
      num-cpus: "1"
    template:
      spec:
        containers:
        - name: ray-worker
          image: ${RAY_IMAGE}
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: "1"
              memory: 2Gi
YAML

等待 RayCluster 报告 ready,然后确认头 Pod 和工作 Pod 正在运行:

kubectl wait \
  --for=jsonpath='{.status.state}'=ready \
  raycluster/"$RAY_CLUSTER_NAME" \
  --namespace "$RAY_NAMESPACE" \
  --timeout=10m

kubectl get raycluster,pods --namespace "$RAY_NAMESPACE"

将 HTTP 模式 RayJob 作业提交到现有群集。 该作业在工作器上运行四个远程任务,并在验证其结果后打印成功标记:

kubectl apply -f - <<YAML
apiVersion: ray.io/v1
kind: RayJob
metadata:
  name: ${RAY_JOB_NAME}
  namespace: ${RAY_NAMESPACE}
spec:
  jobId: ${RAY_JOB_NAME}
  submissionMode: HTTPMode
  clusterSelector:
    ray.io/cluster: ${RAY_CLUSTER_NAME}
  entrypoint: >-
    python3 -c "import ray; ray.init(address='auto'); square=ray.remote(lambda x: x*x);
    values=ray.get([square.remote(i) for i in range(4)]);
    assert values == [0, 1, 4, 9], values;
    print('KUBERAY_SAMPLE_OK', values, flush=True)"
  shutdownAfterJobFinishes: false
YAML

等待作业成功完成:

kubectl wait \
  --for=jsonpath='{.status.jobStatus}'=SUCCEEDED \
  rayjob/"$RAY_JOB_NAME" \
  --namespace "$RAY_NAMESPACE" \
  --timeout=10m

从头 Pod 读取 Ray 驱动程序日志:

HEAD_POD="$(kubectl get pods \
  --namespace "$RAY_NAMESPACE" \
  --selector="ray.io/cluster=$RAY_CLUSTER_NAME,ray.io/node-type=head" \
  --output jsonpath='{.items[0].metadata.name}')"

kubectl exec \
  --namespace "$RAY_NAMESPACE" \
  "$HEAD_POD" \
  --container ray-head \
  -- sh -c 'grep -h "KUBERAY_SAMPLE_OK" /tmp/ray/session_latest/logs/job-driver-*.log'

预期的输出为:

KUBERAY_SAMPLE_OK [0, 1, 4, 9]

此输出确认操作员创建了 Ray 群集,提交了作业,并在工作器上运行任务。 完成后,请删除示例资源:

kubectl delete namespace "$RAY_NAMESPACE"

更新托管的 KubeRay 扩展

使用“安装托管的 KubeRay 扩展”中的 az k8s-extension extension-types list-versions-by-cluster 命令检查群集有哪些可用版本。

在同一 shell 会话中,或在按照准备环境中的说明重新定义 RESOURCE_GROUP、CLUSTER_NAME、EXTENSION_NAME 和 RELEASE_TRAIN 后,为现有扩展启用自动升级:

az k8s-extension update \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --cluster-type managedClusters \
  --name "$EXTENSION_NAME" \
  --release-train "$RELEASE_TRAIN" \
  --auto-upgrade-minor-version true \
  --yes

启用自动升级时,不要指定 --version。 更新后,重复 验证步骤 并确认已安装的版本。

卸载托管的 KubeRay 扩展

在删除托管的 KubeRay 扩展之前,请确保 RESOURCE_GROUP, CLUSTER_NAME并且 EXTENSION_NAME 仍按 准备环境中所述进行设置。 然后查看现有的 Ray 资源:

kubectl get rayclusters,raycronjobs,rayjobs,rayservices --all-namespaces
  • 暂停计划作业,让正在运行的作业完成,并保留所需的数据和清单。
  • 如果要删除 Ray 工作负载,请在 Operator 仍在运行时删除它们,以便它可以完成清理。

删除扩展实例:

az k8s-extension delete \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --cluster-type managedClusters \
  --name "$EXTENSION_NAME" \
  --yes

Important

删除扩展会保留 Ray CRD 和工作负载,但 Operator 不再管理它们。 请勿将 CRD 删除为清理快捷方式,因为这样做也会删除其自定义资源。

确认 kuberay 扩展不再显示在扩展列表中,并且确认 kuberay-operator 部署已被移除:

az k8s-extension list \
  --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" \
  --cluster-type managedClusters \
  --output table

kubectl get deployments --namespace kuberay-system

后续步骤