Azure Kubernetes Service (AKS)にマネージド KubeRay 拡張機能をインストールする (プレビュー)

Important

AKS のプレビュー機能は、セルフサービスのオプトイン単位で利用できます。プレビューは、"現状有姿のまま" および "利用可能な限度" で提供され、サービスレベルアグリーメントおよび限定保証から除外されるものとします。 AKS プレビューは、ベストエフォートベースでカスタマーサポートによって部分的にカバーされます。そのため、これらの機能は運用環境での使用を目的としていません。詳細については、次のサポート記事を参照してください。

Azure Kubernetes Service (AKS)用のマネージド KubeRay 拡張機能はプレビュー段階です。クラスター上に KubeRay オペレーターと Ray カスタムリソース定義 (CRD) をインストール、管理します: RayCluster、RayJob、RayCronJob、RayService。

この記事では、Azure CLIを使用して拡張機能をインストール、確認、更新、削除する方法について説明します。また、サンプルの Ray ワークロードをデプロイして、オペレーターが Ray リソースを期待どおりに管理していることを確認します。

Prerequisites

Azure サブスクリプション、および Kubernetes 1.34 以降を実行し、AKS がサポートする Azure パブリッククラウドリージョンでマネージド ID を使用する AKS クラスター。クラスターがない場合は、「Azure CLI を使用して AKS クラスターを作成する」を参照してください。
Azure CLIの現在のバージョン。
k8s-extension Azure CLI 拡張機能バージョン 1.8.0 以降。
kubectl は、クラスターの Kubernetes バージョンと互換性があります。
Azureリソースプロバイダーの登録、クラスター拡張機能の管理、クラスター資格情報の取得、Kubernetes リソースの検査を行うアクセス許可。

Limitations

既存のオープンソースソフトウェア (OSS) KubeRay のインストール環境: マネージド KubeRay 拡張機能 (microsoft.kuberay) をインストールする前に、既存のセルフホスト型 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 拡張機能をインストールすると、管理コマンドが提供されます。CLI 拡張機能をインストールしても、KubeRay はクラスターにインストールされません。

既存の OSS KubeRay オペレーターをアンインストールする

セルフホスト型のオペレーターをお持ちでない場合は、この手順をスキップしてください。それ以外の場合は、ワークロードデータとマニフェストをバックアップし、RayCronJob のスケジュールを一時停止し、実行中のジョブが終了するのを待ってから、オペレーターを削除してください。

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 分かかる場合があります。コマンド出力に次の値が表示されるまで待ってから、オペレーターのデプロイが使用可能であり、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 リソースを調整して分散タスクを実行できることを確認します。このサンプルでは、1 つのヘッドポッドと 1 つのワーカーポッドを使用します。

サンプルリソース名と 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を報告するのを待ってから、ヘッドポッドとワーカーポッドが実行されていることを確認します。

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 を送信します。ジョブはワーカーで 4 つのリモートタスクを実行し、結果を検証した後に成功マーカーを出力します。

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

ヘッドポッドから 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 拡張機能を更新する

クラスターで使用できるバージョンを確認するには、az k8s-extension extension-types list-versions-by-clusterのコマンドを使用します。

同じシェルセッションで、またはRELEASE_TRAINで説明されているように、RESOURCE_GROUP、CLUSTER_NAME、およびEXTENSION_NAMEを再定義した後、既存の拡張機能の自動アップグレードを有効にします。

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 拡張機能を削除する前に、EXTENSION_NAMEで説明されているように、、RESOURCE_GROUP、および CLUSTER_NAME が引き続き設定されていることを確認してください。次に、既存の Ray リソースを確認します。

kubectl get rayclusters,raycronjobs,rayjobs,rayservices --all-namespaces

スケジュールされたジョブを中断し、実行中のジョブを完了させ、必要なデータとマニフェストを保持します。
Ray ワークロードを削除する場合は、オペレーターの実行中にそれらを削除して、クリーンアップを完了できるようにします。

拡張機能インスタンスを削除します。

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-10-29