Installare e configurare Kueue nel servizio Azure Kubernetes

Kueue fornisce accodamento dei processi e ammissione delle risorse nativi di Kubernetes per carichi di lavoro batch e di intelligenza artificiale in esecuzione su Servizio Azure Kubernetes (AKS). Questo articolo descrive due modi per installare Kueue in AKS:

  • Estensione Kueue gestita di AKS (anteprima): usare l'esperienza di estensione gestita di Azure per distribuire Kueue nel cluster AKS.
  • Kueue open source con Helm: installare e configurare Kueue direttamente dal chart Helm Kueue upstream.

Dopo l'installazione, usare le API Kueue, ad esempio ClusterQueue, LocalQueue e ResourceFlavor per controllare il modo in cui i carichi di lavoro vengono ammessi alle risorse del cluster.

Che cos'è Kueue?

Kueue è un progetto open source di accodamento di processi nativo di Kubernetes progettato per gestire i carichi di lavoro batch e garantire una pianificazione efficiente, equa e basata sui criteri nei cluster Kubernetes. Kueue si integra con l'ecosistema di pianificazione Kubernetes per coordinare l'allocazione delle risorse, la definizione delle priorità e il controllo della capacità per i carichi di lavoro. Kueue controlla se i carichi di lavoro vengono ammessi in base alle quote e ai criteri delle risorse configurati. Dopo l'ammissione di un workload, lo scheduler di Kubernetes inserisce i pod del workload nei nodi.

Kueue è utile per i carichi di lavoro, ad esempio:

  • Addestramento di intelligenza artificiale e machine learning
  • Attività ad alto utilizzo della GPU
  • Elaborazione dati
  • Analisi delle vulnerabilità di sicurezza
  • Codifica multimediale e transcodifica video
  • Generazione di report e analisi finanziaria
  • Altri carichi di lavoro batch che possono attendere la disponibilità di risorse sufficienti

Modellare questi carichi di lavoro usando un processo Kubernetes, CronJob o una definizione di risorsa personalizzata (CRD) come RayJob o Kubeflow MPIJob e ammetterli in base ai relativi ClusterQueue e LocalQueue

Informazioni sulle code Kueue

Prima di inviare carichi di lavoro con Kueue, configurare le code che controllano l'ammissione del carico di lavoro.

Kueue usa due risorse di coda primarie:

  • ClusterQueue definisce le quote di risorse a livello di cluster per i pool di risorse condivise (ad esempio CPU, memoria, quote GPU) e criteri che determinano quali carichi di lavoro possono essere ammessi.
  • LocalQueue fornisce una coda con ambito del namespace in cui gli utenti inviano carichi di lavoro e fanno riferimento a ClusterQueue.

Il flusso seguente illustra come Kueue valuta un carico di lavoro prima che Kubernetes pianifichi i pod: Carico di lavoro (pod, Job e così via) → LocalQueue → ClusterQueue → l'ammissione del carico di lavoro → pianificazione kubernetes

Un LocalQueue identifica il ClusterQueue che deve valutare il carico di lavoro. ClusterQueue determina se è disponibile una quota sufficiente per ammettere il carico di lavoro. Gli amministratori della piattaforma configurano in genere risorse e criteri a livello di cluster, mentre i proprietari del carico di lavoro inviano processi tramite LocalQueue.

Annotazioni

Per inviare un carico di lavoro a Kueue, aggiungere l'etichetta kueue.x-k8s.io/queue-name: <local-queue-name> al carico di lavoro. Questa etichetta associa il carico di lavoro a LocalQueue, che lo instrada alla ClusterQueue appropriata per l'ammissione.

Importante

Il software open source è citato nella documentazione e negli esempi di AKS (Azure Kubernetes Service). Il software che distribuisci è escluso dagli accordi sul livello di servizio di AKS, dalla garanzia limitata e dal supporto Azure. Quando si utilizza la tecnologia open source insieme ad AKS, consultare le opzioni di supporto disponibili dalle rispettive community e dai manutentori di progetti per sviluppare un piano.

Microsoft si assume la responsabilità di creare i pacchetti open source che distribuiamo su AKS. Tale responsabilità include la completa gestione dei processi di build, scan, firma, validazione e hotfix, oltre al controllo dei file binari nelle immagini dei contenitori. Per altre informazioni, vedere Gestione delle vulnerabilità per il servizio Azure Kubernetes e Copertura del supporto del servizio Azure Kubernetes.

Quando usare Kueue

I carichi di lavoro batch e di intelligenza artificiale possono avere requisiti di pianificazione e gestione delle risorse diversi dai servizi Kubernetes a esecuzione prolungata. Gli amministratori dei carichi di lavoro batch (inclusi gli amministratori della piattaforma o del cluster e gli ingegneri DevOps) e gli utenti batch (data scientist, sviluppatori e ingegneri ML) possono trarre vantaggio dalla distribuzione di carichi di lavoro con Kueue su AKS.

Un amministratore batch è incentrato sulla configurazione, la gestione e la protezione dell'infrastruttura a livello di piattaforma per supportare i carichi di lavoro batch e avere le responsabilità seguenti:

  • Effettuare il provisioning e gestire i pool di nodi del servizio Azure Kubernetes.
  • Definire quote di risorse, ClusterQueues e criteri per l'isolamento del carico di lavoro.
  • Ottimizzare l'autoscalabilità e l'efficienza dei costi, ad esempio mediante Cluster Autoscaler o le quote di Kueue.
  • Controllare l'integrità del cluster e della coda.
  • Creare e gestire modelli e flussi di lavoro riutilizzabili.

Un utente batch esegue processi a elevato utilizzo di calcolo o paralleli usando l'infrastruttura a livello di piattaforma configurata da un amministratore batch e in genere:

  • Inviare processi batch (ad esempio Job, carico di lavoro o controller CRD personalizzato) e monitorare lo stato e gli output dei processi
  • Selezionare la coda o la versione di risorsa appropriata per i processi (in base alle indicazioni degli amministratori batch)
  • Ottimizzare le specifiche dei processi per le esigenze di risorse e prestazioni

Prerequisiti

I prerequisiti aggiuntivi dipendono dal metodo di installazione scelto.

Scegliere come installare Kueue

Il servizio Azure Kubernetes supporta due approcci di installazione per Kueue. Scegliere l'opzione più adatta alla modalità di installazione e configurazione di Kueue nel cluster. Le API Kubernetes di Kueue e i concetti di accodamento rimangono invariati indipendentemente dal metodo di installazione. La differenza principale è il modo in cui i componenti Kueue vengono installati e configurati.

Percorso di installazione Description
Estensione Kueue gestita da AKS (anteprima) Si vuole distribuire Kueue tramite l'esperienza di estensione del cluster del servizio Azure Kubernetes e usare la versione e la configurazione kueue supportate dall'estensione.
Kueue open source con Helm Si vuole installare Kueue direttamente dal progetto upstream e controllare la versione di Kueue, i controlli delle funzionalità, le integrazioni e la configurazione Helm.

Installare e configurare l'estensione Kueue gestita in servizio Azure Kubernetes (anteprima)

L'estensione Kueue gestita di AKS fornisce un percorso di installazione nativo di Azure per la distribuzione di Kueue in un cluster AKS. Usare questo metodo di installazione se si vuole distribuire Kueue tramite l'esperienza di estensione del cluster AKS anziché installare direttamente il chart Helm upstream.

Prerequisiti dell'estensione gestita

Prima di iniziare, assicurarsi di disporre degli strumenti seguenti:

  • AKS versione 1.34 o successiva
  • interfaccia della riga di comando di Azure versione 2.56 o successiva
  • versione di kubectl 1.33–1.35
  • interfaccia della riga di comando di Azure k8s-extension versione 1.9.3 o successiva

Limitations

  • L'estensione Kueue gestita del servizio Azure Kubernetes supporta attualmente solo Cluster Autoscaler con supporto per il provisioning automatico del nodo pianificato.
  • AKS Automatic non è ancora supportato. Il supporto è pianificato per una versione successiva.
  • È prima necessario rimuovere le installazioni di OSS Kueue esistenti. Managed Kueue è un singleton del cluster e l'installazione rifiuta un controller Kueue non gestito, anche in un altro spazio dei nomi.
  • Integrazioni dei carichi di lavoro supportate: Job Kubernetes, Pod, Deployment, StatefulSet, JobSet, Ray, MPIJob e Trainer v2 TrainJob.
  • Integrazioni dei carichi di lavoro non supportate: processi Kubeflow v1 legacy, AppWrapper e LeaderWorkerSet.

Installare l'estensione Kueue gestita

Impostare le variabili di ambiente per la sottoscrizione Azure, il gruppo di risorse e il cluster AKS:

RESOURCE_GROUP="<resource-group-name>"
CLUSTER_NAME="<aks-cluster-name>"

Installare l'estensione del cluster Kueue:

az k8s-extension create \
--resource-group "$RESOURCE_GROUP" \
--cluster-name "$CLUSTER_NAME" \
--cluster-type managedClusters \
--name aks-kueue \
--extension-type microsoft.kueue \
--release-train preview

Verificare l'installazione dell'estensione

Ottenere lo stato di provisioning e la versione installata dell'estensione Kueue. Verificare che provisioningState sia Succeeded e extensionState sia Available. Continuare quindi con Confermare lo stato della distribuzione.

az k8s-extension show \
--resource-group "$RESOURCE_GROUP" \
--cluster-name "$CLUSTER_NAME" \
--cluster-type managedClusters \
--name kueue \
--output json

Disinstalla l'estensione Kueue gestita

La disinstallazione di Managed Kueue elimina tutte le risorse personalizzate Kueue nel cluster, tra cui localQueues, ClusterQueues, ResourceFlavors e altre configurazioni kueue create dal cliente. Cancella anche i finalizzatori che bloccano l'eliminazione. Mantenere la configurazione di proprietà del cliente in Git o esportarla prima della disinstallazione. Riapplicarlo dopo aver reinstallato Kueue e prima di ammettere i Jobs in coda. Se si usa GitOps, sospendere la riconciliazione prima di disinstallare Kueue e riprenderla dopo la reinstallazione di Kueue.

I processi Kubernetes gestiti da Kueue e i relativi pod non vengono eliminati:

  • I processi e i pod in esecuzione continuano senza la gestione di Kueue.
  • I processi accodati rimangono sospesi e non creano pod.
  • Dopo aver reinstallato Kueue, Kueue crea nuovi Workloads per i Jobs sopravvissuti che hanno ancora un'etichetta di coda.

Se si vuole rimuovere Kueue gestito da AKS senza eliminare il cluster AKS, eliminare l'estensione:

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

Installare Kueue con Helm

Prerequisiti Helm

Prima di iniziare, assicurarsi di disporre degli strumenti seguenti:

  • Helm v3.0.0 o una versione successiva
  • Autorizzazioni per creare ed eliminare: gruppi di risorse, cluster del servizio Azure Kubernetes, pool di nodi del servizio Azure Kubernetes ed estensioni del cluster

Configurare le funzionalità facoltative di Kueue

Anche se la maggior parte delle funzionalità e dei criteri di pianificazione che potrebbero essere necessari sono abilitate per impostazione predefinita, alcune non lo sono come TopologyAwareScheduling. Se necessario, riconfigurare l'installazione di Kueue modificando le funzionalità predefinite o configurando i valori del paramater Kueue nel values.yaml file del grafico Helm.

Kueue supporta più framework di carico di lavoro che è necessario abilitare in modo esplicito per usare le funzionalità di pianificazione e gestione delle risorse di Kueue quando si eseguono MPIJobs MPI Operator, RayJobdi KubeRay e altro ancora.

L'esempio seguente abilita:

  • LocalQueueMetrics fornisce metriche di Prometheus dettagliate specifiche dello stato e dell'attività di LocalQueues, consentendo il monitoraggio dettagliato dell'ammissione del carico di lavoro, della prenotazione della quota e dell'utilizzo delle risorse.
  • TopologyAwareScheduling consente la pianificazione dei pod in base alla topologia dei nodi in un pool o in un cluster per migliorare la larghezza di banda disponibile tra i pod.
  • Integrazioni per framework del carico di lavoro batch e di intelligenza artificiale, tra cui Kubeflow, Ray e JobSet.

  1. Creare e salvare un values.yaml file per personalizzare facoltativamente la configurazione di Kueue.

    cat <<EOF > values.yaml
controllerManager:
  featureGates:
    - name: TopologyAwareScheduling
      enabled: true
    - name: LocalQueueMetrics
      enabled: true
  managerConfig:
    controllerManagerConfigYaml: |
      apiVersion: config.kueue.x-k8s.io/v1beta1
      kind: Configuration
      integrations:
        frameworks:
          - batch/job
          - kubeflow.org/mpijob
          - ray.io/rayjob
          - ray.io/raycluster
          - jobset.x-k8s.io/jobset
          - kubeflow.org/paddlejob
          - kubeflow.org/pytorchjob
          - kubeflow.org/tfjob
          - kubeflow.org/xgboostjob
          - kubeflow.org/jaxjob
EOF

Annotazioni

Aggiornare la versione in base alle esigenze: kueue/releases

  1. Installare la versione più recente del controller Kueue e dei CRD in uno spazio dei nomi dedicato usando il comando helm install.

    LATEST_VERSION=$(curl -s https://api.github.com/repos/kubernetes-sigs/kueue/releases/latest | grep tag_name | cut -d '"' -f 4 | sed 's/^v//')

helm install kueue oci://registry.k8s.io/kueue/charts/kueue \
 --version=${LATEST_VERSION} \
--create-namespace --namespace=kueue-system \
--values values.yaml

  2. Verificare lo stato della distribuzione usando il helm list comando .

    helm list --namespace kueue-system

    L'output dovrebbe includere un Status di deployed e avere l'aspetto seguente:

    Pulled: registry.k8s.io/kueue/charts/kueue:0.13.4
Digest: -
NAME: kueue
LAST DEPLOYED: -
NAMESPACE: kueue-system
STATUS: deployed
REVISION: 1
TEST SUITE: None

Disinstallare Kueue

Se non sono più necessari il gestore del controller Kueue o le risorse personalizzate Kueue nel cluster del servizio Azure Kubernetes, disinstallare il repository Helm e rimuovere lo spazio dei nomi e le risorse dedicati.

  1. Disinstalla il repository Helm Kueue usando il comando helm uninstall.

    helm uninstall kueue --namespace kueue-system

  2. Rimuovere lo spazio dei nomi dedicato e le risorse dedicate usando il comando kubectl delete.

    kubectl delete namespace kueue-system

Confermare lo stato della distribuzione

Indipendentemente dal metodo di installazione usato, verificare che i componenti Kueue siano in esecuzione prima di configurare le code o inviare carichi di lavoro.

  1. Verificare che i pod controller siano in esecuzione correttamente.

    kubectl get deploy -n kueue-system

    L'output dovrebbe essere simile all'esempio di output seguente:

    NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
kueue-controller-manager       1/1     1            1           7s

Per l'estensione Kueue gestita del servizio Azure Kubernetes, l'output deve includere sia kueue-controller-manager che kueue-extension. Verificare che entrambe le distribuzioni mostrino READY e AVAILABLE come 1.

  1. Confermare l'installazione delle risorse Kueue sul cluster AKS.

    kubectl get crds | grep kueue

    L'output dovrebbe includere i seguenti CRD di Kueue:

    admissionchecks.kueue.x-k8s.io                   2025-09-11T18:20:48Z
clusterqueues.kueue.x-k8s.io                     2025-09-11T18:20:48Z
cohorts.kueue.x-k8s.io                           2025-09-11T18:20:48Z
localqueues.kueue.x-k8s.io                       2025-09-11T18:20:48Z
multikueueclusters.kueue.x-k8s.io                2025-09-11T18:20:48Z
multikueueconfigs.kueue.x-k8s.io                 2025-09-11T18:20:48Z
provisioningrequestconfigs.kueue.x-k8s.io        2025-09-11T18:20:48Z
resourceflavors.kueue.x-k8s.io                   2025-09-11T18:20:48Z
topologies.kueue.x-k8s.io                        2025-09-11T18:20:48Z
workloadpriorityclasses.kueue.x-k8s.io           2025-09-11T18:20:48Z
workloads.kueue.x-k8s.io                         2025-09-11T18:20:48Z

Il set esatto di CRDs può variare a seconda della versione di Kueue installata.

Dopo l'esecuzione di Kueue, configurare code, quote di risorse e criteri di ammissione del carico di lavoro prima di inviare carichi di lavoro.

Passaggi successivi

  • Ultimo aggiornamento: