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