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

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

本文介绍如何使用Azure CLI安装、验证、更新和删除扩展。 可以单独管理 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 安装：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 扩展问题。

更新托管的 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

确认 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

后续步骤

• 对 AKS 上的托管 KubeRay 扩展进行故障排除。
• 在 AKS 上使用 Kueue 运行 Ray AI 工作负载。