Installer l’extension KubeRay gérée sur Azure Kubernetes Service (AKS) (préversion)

L’extension KubeRay gérée pour Azure Kubernetes Service (AKS) est en préversion. Il installe et gère l’opérateur KubeRay et les définitions de ressources personnalisées Ray (CRD) sur votre cluster : RayCluster, RayJob, RayCronJob, et RayService.

Cet article explique comment installer, vérifier, mettre à jour et supprimer l’extension à l’aide du Azure CLI. Vous déployez également un exemple de charge de travail Ray pour confirmer que l’opérateur gère les ressources Ray comme prévu.

Prerequisites

• Un abonnement Azure et un cluster AKS qui exécute Kubernetes 1.34 ou version ultérieure et utilise une identité managée dans une région du cloud public Azure prise en charge par AKS. Si vous n'avez pas de cluster, consultez Créer un cluster AKS à l'aide de la Azure CLI.
• Version actuelle du Azure CLI.
• L’extension Azure CLI k8s-extension version 1.8.0 ou ultérieure.
• kubectl compatible avec la version Kubernetes de votre cluster.
• Autorisations pour inscrire les fournisseurs de ressources Azure, gérer les extensions de cluster, récupérer les informations d’identification du cluster et inspecter les ressources Kubernetes.

Limitations

• Installations de KubeRay (OSS) open source existantes :désinstallez tout opérateur KubeRay auto-hébergé existant avant d’installer l’extension KubeRay gérée (microsoft.kuberay). Une installation rejetée peut toujours modifier les schémas Ray CRD et la propriété des ressources, et la suppression de l’extension ayant échoué n’annule pas ces modifications. Conservez les CRD et les ressources de charges de travail. Si une installation a déjà échoué, suivez les instructions de récupération avant de réessayer.

Préparer votre environnement

Les exemples suivants utilisent Bash. Définissez votre abonnement et les détails du cluster existant, puis connectez-vous :

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"

Vérifiez la version kubernetes du cluster. Vérifiez que la version retournée est 1.34 ou ultérieure avant de continuer :

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

Connectez-vous au cluster :

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

Installez ou mettez à jour l’extension CLI et enregistrez les fournisseurs de ressources requis :

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

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

Vérifiez la version de l’extension CLI installée :

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

L’installation de l’extension CLI fournit des commandes de gestion ; elle n’installe pas KubeRay sur votre cluster.

Désinstaller un opérateur OSS KubeRay existant

Ignorez cette étape si vous n’avez pas d’opérateur auto-hébergé. Sinon, sauvegardez les données et les manifestes de charge de travail, suspendez les planifications RayCronJob et attendez que les travaux en cours d’exécution se terminent avant de supprimer l’opérateur.

Pour une installation Helm, recherchez le nom de version et l’espace de noms :

helm list --all-namespaces

Supprimez uniquement la release de l’opérateur et vérifiez que son déploiement a disparu :

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"

Vérifiez que l’espace de noms conservé s’affiche Active et que chaque CRD conservé *.ray.io s’affiche True dans la ESTABLISHED colonne :

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

Si l’espace de noms est en cours de suppression ou qu’un CRD Ray n’est pas établi, résolvez le problème avant d’activer l’extension.

Pour les autres méthodes d’installation, utilisez leur procédure de suppression de l’opérateur. Conservez les CRD Ray et les ressources de charge de travail ; ne supprimez pas leurs espaces de noms ni leurs CRD.

Installer l’extension KubeRay managée

Répertoriez les versions d’extension disponibles pour votre cluster et la formation de mise en production 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

Vérifiez qu’une version compatible est retournée. Si rien n’est renvoyé, consultez Résoudre les problèmes de détection de la version de l’extension.

Créez l’extension avec les mises à niveau automatiques activées. La commande utilise les valeurs suivantes :

• --extension-type microsoft.kuberay installe l’extension KubeRay managée.
• --scope cluster installe l’extension pour l’ensemble du cluster.
• --release-namespace kuberay-system définit l’espace de noms du kuberay-operator déploiement.
• --release-train "$RELEASE_TRAIN" sélectionnez la formation de mise en production preview.
• --auto-upgrade-minor-version true permet les mises à niveau automatiques. Ne spécifiez pas --version avec ce paramètre.

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

Vérifier l’installation de l’extension

Inspectez la version installée et l’état de provisionnement :

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

L’installation peut prendre jusqu’à 15 minutes. Attendez que la sortie de la commande affiche les valeurs suivantes, puis vérifiez que le déploiement de l’opérateur est disponible et que les CRD Ray sont installés :

• provisioningState a la valeur Succeeded.
• extensionState est Available ou 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

Si les vérifications d’approvisionnement ou de préparation échouent, consultez Résoudre les problèmes liés à l’extension KubeRay managée.

Exécuter un exemple de charge de travail Ray

Déployez un cluster utilisant uniquement des CPU RayCluster et soumettez un RayJob pour confirmer que l’opérateur KubeRay peut réconcilier les ressources Ray et exécuter des tâches distribuées. L’exemple utilise un pod principal et un pod worker.

Définissez les noms de ressources d’exemple et l’image 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"

Créez un espace de noms et déployez le 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

Attendez que le RayCluster signale ready, puis vérifiez que les pods head et worker sont en cours d’exécution :

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

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

Envoyez un RayJob en mode HTTP au cluster existant. La tâche exécute quatre tâches distantes sur le worker et imprime un marqueur de réussite après avoir validé leurs résultats :

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

Attendez que le job se termine avec succès :

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

Lisez le journal du driver Ray à partir du pod principal :

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'

La sortie attendue est :

KUBERAY_SAMPLE_OK [0, 1, 4, 9]

Cette sortie confirme que l’opérateur a créé le cluster Ray, soumis le job et exécuté des tâches sur le worker. Supprimez les ressources d’exemple lorsque vous avez terminé :

kubectl delete namespace "$RAY_NAMESPACE"

Mettre à jour l’extension KubeRay managée

Utilisez la commande az k8s-extension extension-types list-versions-by-cluster dans Installer l’extension KubeRay managée pour vérifier les versions disponibles pour votre cluster.

Dans la même session d’interpréteur de commandes, ou après avoir redéfini RESOURCE_GROUP, CLUSTER_NAMEet EXTENSION_NAMERELEASE_TRAIN comme décrit dans Préparer votre environnement, activez les mises à niveau automatiques pour une extension existante :

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

Ne spécifiez pas --version quand les mises à niveau automatiques sont activées. Après la mise à jour, répétez les étapes de vérification et confirmez la version installée.

Désinstaller l’extension KubeRay gérée

Avant de supprimer l’extension KubeRay managée, assurez-vous que RESOURCE_GROUP, CLUSTER_NAME et EXTENSION_NAME sont toujours définis comme décrit dans Préparer votre environnement. Passez ensuite en revue les ressources Ray existantes :

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

• Suspendez les tâches planifiées, laissez les tâches en cours d’exécution se terminer et conservez les données et manifestes requis.
• Si vous souhaitez supprimer des charges de travail Ray, supprimez-les pendant que l’opérateur est toujours en cours d’exécution afin qu’il puisse effectuer le nettoyage.

Supprimez l’instance d’extension :

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

Vérifiez que l’extension kuberay n’apparaît plus dans la liste des extensions et que le kuberay-operator déploiement est supprimé :

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

kubectl get deployments --namespace kuberay-system

Étapes suivantes

• Résolvez les problèmes liés à l’extension KubeRay gérée sur AKS.
• Exécutez des charges de travail Ray AI avec Kueue sur AKS.