Instalación y configuración de Kueue en Azure Kubernetes Service (AKS)

Kueue proporciona colas de trabajos nativos de Kubernetes y admisión de recursos para cargas de trabajo por lotes e inteligencia artificial que se ejecutan en Azure Kubernetes Service (AKS). En este artículo se describen dos maneras de instalar Kueue en AKS:

  • Extensión kueue administrada de AKS (versión preliminar): use la experiencia de extensión administrada Azure para implementar Kueue en el clúster de AKS.
  • Kueue de código abierto con Helm: instale y configure Kueue directamente desde el chart de Helm de Kueue original.

Después de la instalación, use las API de Kueue, como ClusterQueue, LocalQueue y ResourceFlavor para controlar cómo se admiten las cargas de trabajo en los recursos del clúster.

¿Qué es Kueue?

Kueue es un proyecto de cola de trabajos nativos de Kubernetes de código abierto diseñado para administrar cargas de trabajo por lotes y garantizar una programación eficaz, justa y controlada por directivas en clústeres de Kubernetes. Kueue se integra con el ecosistema de planificación de Kubernetes para coordinar la asignación de recursos, la priorización y el control de capacidad de las cargas de trabajo. Kueue controla si las cargas de trabajo se admiten en función de las directivas y cuotas de recursos configuradas. Una vez admitida una carga de trabajo, el planificador de Kubernetes coloca los pods de la carga de trabajo en los nodos.

Kueue es útil para cargas de trabajo como:

  • Entrenamiento en inteligencia artificial y aprendizaje automático
  • tareas intensivas en GPU
  • Procesamiento de datos
  • Análisis de vulnerabilidades de seguridad
  • Codificación multimedia y transcodificación de vídeo
  • Generación de informes y análisis financiero
  • Otras cargas de trabajo por lotes que pueden esperar a que haya suficientes recursos disponibles

Modele estas cargas de trabajo mediante un trabajo de Kubernetes, CronJob o una definición de recursos personalizados (CRD), como RayJob o Kubeflow MPIJob, y admítalas según sus ClusterQueue y LocalQueue

Comprender las colas de Kueue

Antes de enviar cargas de trabajo con Kueue, configure colas que controlan la admisión de cargas de trabajo.

Kueue usa dos recursos de cola principales:

  • ClusterQueue define cuotas de recursos en todo el clúster para los grupos de recursos compartidos (como las cuotas de CPU, memoria y GPU) y las directivas que determinan qué cargas de trabajo pueden admitirse.
  • LocalQueue proporciona una cola con ámbito de espacio de nombres donde los usuarios envían cargas de trabajo y hacen referencia a ClusterQueue.

En el flujo siguiente se muestra cómo Kueue evalúa una carga de trabajo antes de que Kubernetes programe sus pods: Carga de trabajo (pod, Job, etc.) → LocalQueue → ClusterQueue → admisión de cargas de trabajo → programación de Kubernetes

Un LocalQueue identifica el ClusterQueue que debe evaluar la carga de trabajo. ClusterQueue determina si hay suficiente cuota disponible para que se admita la carga de trabajo. Los administradores de la plataforma suelen configurar los recursos y las directivas en el nivel del clúster, mientras que los propietarios de las cargas de trabajo envían los trabajos a través de un LocalQueue.

Nota:

Para enviar una carga de trabajo a Kueue, agregue la etiqueta kueue.x-k8s.io/queue-name: <local-queue-name> a la carga de trabajo. Esta etiqueta asocia la carga de trabajo a LocalQueue, que la enruta a la ClusterQueue adecuada para la admisión.

Importante

El software de código abierto se menciona en toda la documentación y ejemplos de AKS. El software que implemente se excluye de los contratos de nivel de servicio de AKS, la garantía limitada y el soporte técnico de Azure. A medida que usa la tecnología de código abierto junto con AKS, consulte las opciones de soporte técnico disponibles en las comunidades y los mantenedores de proyectos respectivos para desarrollar un plan.

Microsoft asume la responsabilidad de crear los paquetes de código abierto que implementamos en AKS. Esa responsabilidad incluye ser plenamente responsable del proceso de compilación, escaneo, firma, validación y corrección rápida, junto con el control de los binarios en las imágenes de contenedor. Para obtener más información, consulte Administración de vulnerabilidades para AKS y Cobertura del soporte técnico de AKS.

Cuándo usar Kueue

Las cargas de trabajo de Batch e AI pueden tener requisitos de programación y administración de recursos que difieren de los servicios de Kubernetes de ejecución prolongada. Los administradores de cargas de trabajo de Batch (incluidos los administradores de plataformas o clústeres y los ingenieros de DevOps) y los usuarios de Batch (científicos de datos, desarrolladores e ingenieros de aprendizaje automático) pueden beneficiarse de la implementación de cargas de trabajo con Kueue en AKS.

Un administrador por lotes se centra en configurar, administrar y proteger la infraestructura de nivel de plataforma para admitir cargas de trabajo por lotes y tiene las siguientes responsabilidades:

  • Aprovisionar y administrar grupos de nodos de AKS.
  • Defina cuotas de recursos, ClusterQueues y directivas para el aislamiento de cargas de trabajo.
  • Ajuste el escalado automático y la eficiencia de costos (como el escalador automático de clústeres o las cuotas de Kueue).
  • Monitorizar el estado del clúster y de la cola.
  • Crear y mantener plantillas y flujos de trabajo reutilizables.

Un usuario por lotes ejecuta trabajos de proceso intensivo o paralelo mediante la infraestructura de nivel de plataforma configurada por un administrador de lotes y normalmente:

  • Enviar trabajos por lotes (como trabajos, cargas de trabajo o CRD de controlador personalizados) y supervisar el estado y las salidas del trabajo
  • Seleccione la cola o el tipo de recurso adecuado para los trabajos (según la orientación de los administradores de lotes)
  • Optimización de las especificaciones de trabajo para las necesidades de recursos y rendimiento

Prerrequisitos

Los requisitos previos adicionales dependen del método de instalación que elija.

Elección de cómo instalar Kueue

AKS admite dos enfoques de instalación para Kueue. Elija la opción que mejor coincida con cómo desea instalar y configurar Kueue en el clúster. Las API de Kubernetes de Kueue y los conceptos de puesta en cola siguen siendo los mismos independientemente del método de instalación. La principal diferencia es cómo se instalan y configuran los componentes de Kueue.

Ruta de instalación Description
Extensión Kueue administrada de AKS (versión preliminar) Quiere implementar Kueue a través de la experiencia de extensión de clúster de AKS y usar la versión y la configuración de Kueue compatibles con la extensión.
Kueue de código abierto con Helm Quiere instalar Kueue directamente desde el proyecto upstream y controlar la versión de Kueue, las feature gates, las integraciones y la configuración de Helm.

Instalación y configuración de la extensión kueue administrada en Azure Kubernetes Service (versión preliminar)

La extensión Kueue administrada de AKS proporciona una ruta de instalación nativa de Azure para implementar Kueue en un clúster de AKS. Utilice este método de instalación si desea implementar Kueue a través de la experiencia de extensión de clúster de AKS en lugar de instalar directamente el chart de Helm upstream.

Requisitos previos de la extensión administrada

Antes de empezar, asegúrese de que tiene las siguientes herramientas:

  • AKS versión 1.34 o posterior
  • CLI de Azure versión 2.56 o posterior
  • kubectl versión 1.33–1.35
  • CLI de Azure k8s-extension versión 1.9.3 o posterior

Limitations

  • La extensión de Kueue administrada por AKS actualmente solo admite Cluster Autoscaler, con la compatibilidad con el aprovisionamiento automático de nodos planificada.
  • AKS Automatic aún no se admite. El soporte está previsto para una versión futura.
  • Primero debe quitar las instalaciones existentes de OSS Kueue. Managed Kueue es un singleton de clúster y la instalación rechaza un controlador Kueue no administrado, incluso en otro espacio de nombres.
  • Integraciones de cargas de trabajo admitidas: Kubernetes Job, Pod, Deployment, StatefulSet, JobSet, Ray, MPIJob y Trainer v2 TrainJob.
  • Integraciones de cargas de trabajo no admitidas: trabajos heredados de Kubeflow v1, AppWrapper y LeaderWorkerSet.

Instala la extensión Kueue administrada

Establezca variables de entorno para la suscripción de Azure, el grupo de recursos y el clúster de AKS:

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

Instale la extensión de clúster de 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

Verifica la instalación de la extensión

Obtenga el estado de aprovisionamiento y la versión instalada de la extensión Kueue. Compruebe que provisioningState es Succeeded y extensionState es Available. A continuación, pase a Confirmar el estado de la implementación.

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

Desinstala la extensión Kueue administrada

Al desinstalar Managed Kueue, se eliminan todos los recursos personalizados de Kueue del clúster, incluidos LocalQueues creados por el cliente, ClusterQueues, ResourceFlavors y otra configuración de Kueue. También borra los finalizers que bloquean la eliminación. Mantenga la configuración propiedad del cliente en Git o expórtela antes de desinstalar. Vuelva a aplicarlo después de reinstalar Kueue y antes de admitir Jobs en cola. Si usa GitOps, pause la conciliación antes de desinstalar y reanúdela después de que se reinstale Kueue.

Los trabajos de Kubernetes administrados por Kueue y sus pods no se eliminan:

  • La ejecución de trabajos y pods continúa sin la administración de Kueue.
  • Los trabajos en cola permanecen suspendidos y no crean pods.
  • Después de que se reinstale Kueue, crea nuevas cargas de trabajo para los trabajos supervivientes que aún tengan una etiqueta de cola.

Si desea quitar Kueue administrado sin eliminar el clúster de AKS, elimine la extensión:

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

Instalar Kueue con Helm

Requisitos previos de Helm

Antes de empezar, asegúrese de que tiene las siguientes herramientas:

  • Helm v3.0.0 o versiones posteriores
  • Permisos para crear y eliminar: grupos de recursos, clústeres de AKS, grupos de nodos de AKS y extensiones de clúster

Configurar funciones opcionales de Kueue

Aunque la mayoría de las características y directivas de programación que puede requerir están habilitadas de forma predeterminada, algunas no son como TopologyAwareScheduling. Si es necesario, vuelva a configurar la instalación de Kueue cambiando las puertas de características predeterminadas o configurando los valores de paramater de Kueue en el archivo values.yaml del gráfico de Helm.

Kueue admite varios marcos de carga de trabajo que necesita habilitar explícitamente para usar las funcionalidades de programación y administración de recursos de Kueue al ejecutar MPI Operator MPIJobs, RayJob de KubeRay y mucho más.

El siguiente ejemplo habilita:

  • LocalQueueMetrics proporciona métricas detalladas de Prometheus específicas del estado y la actividad de LocalQueues, lo que permite la supervisión detallada de la admisión de cargas de trabajo, la reserva de cuota y el uso de recursos.
  • TopologyAwareScheduling permite programar pods en función de la topología de los nodos de un grupo o clúster para mejorar el ancho de banda disponible entre los pods.
  • Integraciones para marcos de carga de trabajo por lotes e IA, como Kubeflow, Ray y JobSet.

  1. Cree y guarde un values.yaml archivo para personalizar opcionalmente la configuración de 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

Nota:

Actualizar la versión según sea necesario: kueue/releases

  1. Instale la versión más reciente del controlador Kueue y los CRD utilizando el comando helm install en un espacio de nombres dedicado.

    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. Confirme el estado de implementación mediante el helm list comando .

    helm list --namespace kueue-system

    La salida debe incluir un Status de deployed y un aspecto similar al siguiente:

    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

Desinstalar Kueue

Si ya no necesita el administrador de controladores de Kueue o los recursos personalizados de Kueue en el clúster de AKS, desinstale el repositorio de Helm y quite el espacio de nombres y los recursos dedicados.

  1. Desinstale el repositorio de Helm de Kueue mediante el helm uninstall comando .

    helm uninstall kueue --namespace kueue-system

  2. Quite el espacio de nombres dedicado y los recursos mediante el kubectl delete comando .

    kubectl delete namespace kueue-system

Confirmación del estado de la implementación

Independientemente del método de instalación que use, compruebe que los componentes de Kueue se están ejecutando antes de configurar colas o enviar cargas de trabajo.

  1. Compruebe que los pods del controlador se están ejecutando correctamente.

    kubectl get deploy -n kueue-system

    El resultado debería ser similar al ejemplo siguiente:

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

Para la extensión Kueue administrada de AKS, la salida debe incluir tanto kueue-controller-manager como kueue-extension. Compruebe que ambas implementaciones muestran READY y AVAILABLE como 1.

  1. Confirme la instalación de recursos de Kueue en el clúster de AKS:

    kubectl get crds | grep kueue

    La salida debe incluir los siguientes CRD de 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

El conjunto exacto de CRD puede variar en función de la versión de Kueue instalada.

Una vez que Kueue esté en ejecución, configure colas, cuotas de recursos y directivas de admisión de cargas de trabajo antes de enviar cargas de trabajo.

Pasos siguientes

  • Se actualizó por última vez el