在 Azure Kubernetes Service（AKS）上安裝受控 KubeRay 擴充功能（預覽）

Important

AKS 預覽功能以自助方式提供，並採選擇加入制。預覽版本係依「現狀」及「可用情況」提供，且不適用於服務等級協定與有限保固。客戶支援部門會盡最大努力，部分支援 AKS 預覽。因此，這些功能不適合實際執行用途。如需詳細資訊，請參閱下列支援文章：

Azure Kubernetes Service （AKS）的 managed KubeRay 擴展目前處於預覽階段。它會在您的叢集上安裝並管理 RayCluster 運算子及 Ray 自訂資源定義（CRD）：、RayJob、RayCronJob 和 RayService。

本文將教你如何使用 Azure CLI 安裝、驗證、更新及移除擴充功能。你也會部署一個範例 Ray 工作負載，以確認 Operator 是否如預期般管理 Ray 資源。

Prerequisites

一個 Azure 訂閱，以及一個執行 Kubernetes 1.34 或更新版本，並在 AKS 支援的 Azure 公用雲端區域中使用管理身分的 AKS 叢集。如果你沒有叢集，請參考使用 Azure CLI 建立 AKS 叢集。
Azure CLI 的最新版本。
The k8s-extension Azure CLI 擴充功能 1.8.0 以上版本。
kubectl 與你叢集的 Kubernetes 版本相容。
註冊 Azure 資源提供者、管理叢集擴充、取得叢集憑證及檢查 Kubernetes 資源的權限。

Limitations

現有開源軟體（OSS）KubeRay 安裝：在安裝受管理的 KubeRay 擴充功能（）前，先microsoft.kuberay。遭拒絕的安裝仍可能變更 Ray CRD 結構描述與擁有權，而且刪除失敗的擴充功能也不會復原這些變更。保留 CRD 與工作負載資源。如果安裝已經失敗，請先依照復原指引，再重試。

準備您的作業環境

以下範例使用 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，可以跳過這個步驟。否則，請備份工作負載資料和資訊清單，暫停 RayCronJob 排程，並等待執行中的作業完成後再移除 Operator。

對於 Helm 安裝，請找到發行名稱與命名空間：

helm list --all-namespaces

僅移除操作員版本，並確認其部署已消失：

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 是否在 True 欄位中顯示 ESTABLISHED：

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分鐘。等待指令輸出顯示以下數值，然後確認 Operator 部署可用且 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 操作員能調和 Ray 資源並執行分散式工作。範例使用一個 head Pod 和一個 worker Pod。

設定範例資源名稱與 Ray 映像：

RAY_NAMESPACE="kuberay-sample"
RAY_CLUSTER_NAME="sample-raycluster"
RAY_JOB_NAME="sample-rayjob"
RAY_VERSION="2.58.0"
RAY_IMAGE="mcr.microsoft.com/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，然後確認 head 和 worker 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提交至現有叢集。該工作會於 worker 上執行四項遠端任務，並在驗證結果後列印成功標記：

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

請閱讀 head pod 上的 Ray driver 日誌：

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 與工作負載，但操作員不再管理它們。不要把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

下一步

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-11-03