De beheerde KubeRay-extensie installeren op Azure Kubernetes Service (AKS) (preview)

De beheerde KubeRay-extensie voor Azure Kubernetes Service (AKS) is in preview. Het installeert en beheert de KubeRay-operator en de aangepaste resourcedefinities van Ray (CRD's) op uw cluster: RayCluster, RayJob, RayCronJoben RayService.

In dit artikel leest u hoe u de extensie installeert, verifieert, bijwerkt en verwijdert met behulp van de Azure CLI. U implementeert ook een voorbeeldworkload van Ray om te bevestigen dat de operator Ray-resources beheert zoals verwacht.

Prerequisites

• Een Azure-abonnement en een AKS-cluster waarop Kubernetes 1.34 of hoger wordt uitgevoerd en die beheerde identiteit gebruikt in een door AKS ondersteunde Azure openbare cloudregio. Zie Een AKS-cluster maken met behulp van de Azure CLI als u geen cluster hebt.
• Een huidige versie van de Azure CLI.
• De k8s-extension Azure CLI-extensie versie 1.8.0 of hoger.
• kubectl compatibel met de Kubernetes-versie van uw cluster.
• Machtigingen voor het registreren van Azure resourceproviders, het beheren van clusterextensies, het ophalen van clusterreferenties en het inspecteren van Kubernetes-resources.

Limitations

• Bestaande opensource-software (OSS) KubeRay-installaties:Verwijder een bestaande zelf-gehoste KubeRay-operator voordat u de beheerde KubeRay-extensie (microsoft.kuberay) installeert. Een geweigerde installatie kan nog steeds ray CRD-schema's en eigendom wijzigen en als u de mislukte extensie verwijdert, worden deze wijzigingen niet ongedaan gemaakt. CRDs en workload resources behouden. Als een installatie al is mislukt, volgt u de herstelrichtlijnen voordat u het opnieuw probeert.

Uw omgeving voorbereiden

In de volgende voorbeelden wordt Bash gebruikt. Stel uw abonnement en bestaande clustergegevens in en meld u vervolgens aan:

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"

Controleer de Kubernetes-versie van het cluster. Controleer of de geretourneerde versie 1.34 of hoger is voordat u doorgaat:

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

Verbinding maken met het cluster:

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

Installeer of werk de CLI-extensie bij en registreer de vereiste resourceproviders:

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

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

Controleer de geïnstalleerde CLI-extensieversie:

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

Het installeren van de CLI-extensie biedt beheeropdrachten; KubeRay wordt niet op uw cluster geïnstalleerd.

Een bestaande OSS KubeRay-operator verwijderen

Sla deze stap over als u geen self-hosted operator hebt. Anders moet u een back-up maken van workloadgegevens en manifesten, RayCronJob-planningen onderbreken en wachten tot actieve taken zijn voltooid voordat u de operator verwijdert.

Voor een Helm-installatie zoekt u de releasenaam en namespace:

helm list --all-namespaces

Verwijder alleen de operatorrelease en controleer of de deployment is verdwenen:

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"

Controleer of de bewaarde naamruimte Active toont en elke bewaarde *.ray.io CRD True toont in de kolom ESTABLISHED:

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

Als de naamruimte wordt beëindigd of er geen Ray CRD tot stand is gebracht, los het probleem op voordat u de extensie inschakelt.

Gebruik voor andere installatiemethoden hun operatorverwijderingsprocedure. Ray CRD's en workloadresources behouden; verwijder hun naamruimten of CRD's niet.

De beheerde KubeRay-extensie installeren

Geef de extensieversies weer die beschikbaar zijn voor uw cluster en de preview releasetrein:

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

Controleer of er een compatibele versie wordt geretourneerd. Als er geen wordt geretourneerd, zie Problemen met de detectie van extensieversies oplossen.

Maak de extensie met ingeschakelde automatische upgrades. Het commando gebruikt de volgende waarden:

• --extension-type microsoft.kuberay installeert de beheerde KubeRay-extensie.
• --scope cluster installeert de extensie voor het hele cluster.
• --release-namespace kuberay-system stelt de naamruimte voor de kuberay-operator deployment in.
• --release-train "$RELEASE_TRAIN" selecteert de preview release train.
• --auto-upgrade-minor-version true maakt automatische upgrades mogelijk. Specificeer --version niet met deze instelling.

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

De installatie van de extensie controleren

Controleer de geïnstalleerde versie en provisioningstatus:

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

De installatie kan tot 15 minuten duren. Wacht totdat in de uitvoer van de opdracht de volgende waarden worden weergegeven. Controleer vervolgens of de deployment van de operator beschikbaar is en of de Ray CRD's zijn geïnstalleerd:

• provisioningState is Succeeded.
• extensionState is Available of 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

Als inrichtings- of gereedheidscontroles mislukken, raadpleegt u Problemen met de beheerde KubeRay-extensie oplossen.

Een voorbeeldworkload in Ray uitvoeren

Implementeer een CPU-only RayJob en dien een taak RayCluster in om te bevestigen dat de KubeRay-operator Ray-resources kan reconciliëren en gedistribueerde taken kan uitvoeren. In het voorbeeld wordt één head pod en één worker pod gebruikt.

Stel de namen van de voorbeeldresources en de Ray-afbeelding in:

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"

Maak een naamruimte en deploy de 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

Wacht totdat RayClusterready meldt en controleer vervolgens of de hoofd- en workerpods actief zijn:

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

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

Verzend een HTTP-modusverzoek RayJob naar het bestaande cluster. De taak voert vier externe taken uit op de worker en drukt na het valideren van de resultaten een succesmarkering af:

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

Wacht tot de taak is voltooid:

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

Lees het logboek van de Ray driver van de hoofdpod:

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'

De verwachte uitvoer is:

KUBERAY_SAMPLE_OK [0, 1, 4, 9]

Deze uitvoer bevestigt dat de operator het Ray-cluster heeft gemaakt, de taak heeft verzonden en taken heeft uitgevoerd op de worker-node. Verwijder de voorbeeldresources wanneer u klaar bent:

kubectl delete namespace "$RAY_NAMESPACE"

De beheerde KubeRay-extensie bijwerken

Gebruik de az k8s-extension extension-types list-versions-by-cluster opdracht in De beheerde KubeRay-extensie installeren om te controleren welke versies beschikbaar zijn voor uw cluster.

Schakel in dezelfde shellsessie, of nadat u RESOURCE_GROUP, CLUSTER_NAME, EXTENSION_NAME en RELEASE_TRAIN opnieuw hebt gedefinieerd zoals beschreven in Uw omgeving voorbereiden, automatische upgrades in voor een bestaande extensie:

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

Specificeer --version niet wanneer automatische upgrades zijn ingeschakeld. Herhaal na de update de verificatiestappen en bevestig de geïnstalleerde versie.

De beheerde KubeRay-extensie verwijderen

Voordat u de beheerde KubeRay-extensie verwijdert, moet u controleren of RESOURCE_GROUP, CLUSTER_NAME en EXTENSION_NAME nog steeds zijn ingesteld zoals beschreven in Uw omgeving voorbereiden. Controleer vervolgens bestaande Ray-resources:

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

• Geplande taken onderbreken, actieve taken laten voltooien en vereiste gegevens en manifesten behouden.
• Als u Ray-workloads wilt verwijderen, verwijdert u deze terwijl de operator nog actief is, zodat het opschonen kan worden voltooid.

Verwijder het extensie-exemplaar:

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

Controleer of de kuberay extensie niet meer wordt weergegeven in de extensielijst en of de kuberay-operator uitrol is verwijderd:

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

kubectl get deployments --namespace kuberay-system

Volgende stappen 

• Problemen met de beheerde KubeRay-extensie in AKS oplossen.
• Ray AI-workloads uitvoeren met Kueue op AKS.