Instalar a extensão gerida do KubeRay no Azure Kubernetes Service (AKS) (pré-visualização)

A extensão KubeRay gerida para Azure Kubernetes Service (AKS) está em pré-visualização. Instala e gere o operador KubeRay e as definições personalizadas de recursos (CRDs) Ray no seu cluster: RayCluster, RayJob, RayCronJob, e RayService.

Este artigo mostra-lhe como instalar, verificar, atualizar e remover a extensão usando a CLI do Azure. Também implementa uma carga de trabalho Ray de amostra para confirmar que o operador gere os recursos Ray como esperado.

Prerequisites

• Uma subscrição do Azure e um cluster AKS que executa o Kubernetes 1.34 ou posterior e utiliza identidade gerida numa região de cloud pública Azure suportada por AKS. Se não tiveres cluster, vê Criar um cluster AKS usando a CLI do Azure.
• Uma versão atual da CLI do Azure.
• A extensão do k8s-extension CLI do Azure, versão 1.8.0 ou posterior.
• kubectl compatível com a versão Kubernetes do teu cluster.
• Permissões para registar fornecedores de recursos do Azure, gerir extensões de cluster, recuperar credenciais de cluster e inspecionar recursos Kubernetes.

Limitations

• Instalações KubeRay de software open-source (OSS) existentes:Desinstale qualquer operador KubeRay auto-hospedado existente antes de instalar a extensão KubeRay gerida (microsoft.kuberay). Uma instalação rejeitada ainda pode alterar esquemas e propriedade do Ray CRD, e eliminar a extensão falhada não desfaz essas alterações. Preservar CRDs e recursos de carga de trabalho. Se uma instalação já falhou, siga as orientações de recuperação antes de tentar novamente.

Prepare seu ambiente

Os exemplos seguintes usam Bash. Defina a sua subscrição e os dados do cluster existente, e depois inicie sessão:

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"

Consulte a versão do Kubernetes do cluster. Confirme que a versão retornada é a 1.34 ou posterior antes de continuar:

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

Liga-te ao cluster:

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

Instale ou atualize a extensão CLI e registe os fornecedores de recursos necessários:

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

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

Verifique a versão instalada da extensão CLI:

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

Instalar a extensão CLI fornece comandos de gestão; não instala o KubeRay no teu cluster.

Desinstalar um operador KubeRay OSS existente

Ignora este passo se não tiveres um operador autoalojado. Caso contrário, faça backup dos dados da carga de trabalho e manifestos, suspenda RayCronJob os agendamentos e espere que os trabalhos em execução terminem antes de remover o operador.

Para uma instalação Helm, encontre o nome da release e o espaço de nomes:

helm list --all-namespaces

Remova apenas a release do operador e confirme que a sua implantação desapareceu:

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"

Verifique se o namespace retido aparece como Active e que cada CRD retido *.ray.io aparece True na coluna ESTABLISHED:

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

Se o namespace estiver a terminar ou não for estabelecido um CRD Ray, resolva o problema antes de ativar a extensão.

Para outros métodos de instalação, utilize o respetivo procedimento de remoção do operador. Preservar os CRDs Ray e os recursos de workload; não apague os seus namespaces ou CRDs.

Instalar a extensão KubeRay gerida

Liste as versões de extensão disponíveis para o teu cluster e o preview ciclo de lançamentos:

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

Confirma que uma versão compatível é devolvida. Se nenhuma for devolvida, veja Resolução de problemas da descoberta de versões da extensão.

Crie a extensão com as atualizações automáticas ativadas. O comando utiliza os seguintes valores:

• --extension-type microsoft.kuberay instala a extensão KubeRay gerida.
• --scope cluster Instala a extensão para todo o cluster.
• --release-namespace kuberay-system define o namespace para a kuberay-operator implementação.
• --release-train "$RELEASE_TRAIN" seleciona o preview ramo de lançamento.
• --auto-upgrade-minor-version true Permite atualizações automáticas. Não especifiques --version com esta definição.

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

Verifique a instalação da extensão

Inspecionar a versão instalada e o estado de provisionamento:

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

A instalação pode demorar até 15 minutos. Aguarde até que a saída do comando mostre os seguintes valores, depois verifique se a implantação do operador está disponível e que os CRDs Ray estão instalados:

• provisioningState é Succeeded.
• extensionState é 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

Se as verificações de provisionamento ou prontidão falharem, veja Solucionar problemas da extensão KubeRay gerida.

Executar uma carga de trabalho de exemplo do Ray

Implemente uma configuração apenas de CPU RayCluster e submeta um RayJob para confirmar que o operador KubeRay consegue reconciliar recursos Ray e executar tarefas distribuídas. A amostra utiliza um head pod e um worker pod.

Defina os nomes dos recursos de exemplo e a imagem 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"

Crie um namespace e implemente o 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

Aguarde que o RayCluster apresente ready e depois confirme que os pods head e worker estão a funcionar:

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

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

Submeta um RayJob em modo HTTP ao cluster existente. O trabalho executa quatro tarefas remotas no worker e imprime um marcador de sucesso após validar os resultados:

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

Aguarde até que a tarefa seja concluída com êxito:

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

Leia o registo do driver Ray a partir do head pod:

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'

O resultado esperado é:

KUBERAY_SAMPLE_OK [0, 1, 4, 9]

Esta saída confirma que o operador criou o cluster Ray, submeteu o trabalho e executou tarefas no trabalhador. Apagar os recursos de exemplo quando terminares:

kubectl delete namespace "$RAY_NAMESPACE"

Atualizar a extensão KubeRay gerida

Utilize o comando az k8s-extension extension-types list-versions-by-cluster em Instalar a extensão KubeRay gerida para verificar quais as versões disponíveis para o seu cluster.

Na mesma sessão de shell, ou depois de redefinir RESOURCE_GROUP, CLUSTER_NAME, EXTENSION_NAME, e RELEASE_TRAIN conforme descrito em Preparar o seu ambiente, ative atualizações automáticas para uma extensão existente:

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

Não especifiquem --version quando as atualizações automáticas estão ativadas. Após a atualização, repita os passos de verificação e confirme a versão instalada.

Desinstalar a extensão KubeRay gerida

Antes de remover a extensão KubeRay gerida, certifique-se de que RESOURCE_GROUP, CLUSTER_NAME e EXTENSION_NAME ainda estão definidos conforme descrito em Prepare o seu ambiente. Depois revê os recursos existentes do Ray:

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

• Suspender as tarefas agendadas, deixar as tarefas em execução terminarem e preservar os dados e manifestos necessários.
• Se quiseres eliminar cargas de trabalho do Ray, elimina-as enquanto o operador ainda está a funcionar para que possa completar a limpeza.

Remover a instância da extensão:

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

Confirme que a kuberay extensão já não aparece na lista de extensões e que a kuberay-operator implantação foi removida:

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

kubectl get deployments --namespace kuberay-system

Passos seguintes

• Resolução de problemas da extensão KubeRay gerida no AKS.
• Executar cargas de trabalho Ray AI com Kueue no AKS.