Add custom admission checks to ACK Kube Queue with AdmissionCheck - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Por padrão, o ACK Kube Queue verifica apenas a cota Max definida em uma ElasticQuotaTree. Após passar pela verificação de cota, o agendador processa o workload. Se você precisar de uma lógica mais complexa para validar a remoção da fila, use o mecanismo AdmissionCheck. Esse recurso externo e extensível do ACK Kube Queue executa validações adicionais antes de remover um workload da fila, garantindo o agendamento apenas de workloads elegíveis.

Como funciona

Ao adicionar um AdmissionCheck a um cluster, o ACK Kube Queue não define imediatamente a fase Dequeued para uma QueueUnit após ela passar na verificação de cota. Em vez disso, a QueueUnit entra na fase Reserved, e entradas admissionChecks com estado Pending são adicionadas ao campo status da QueueUnit.

apiVersion: scheduling.x-k8s.io/v1alpha1
kind: QueueUnit
metadata:
  ...
spec:
  ...
status:
  admissionChecks:
  - lastTransitionTime: "2025-01-17T01:46:58Z"
    message: ""
    name: sample-prov
    state: Pending
  lastUpdateTime: "2025-01-17T01:46:58Z"
  message: Reserved resources success, waiting admission checks to be ready
  phase: Reserved
  podState: {}

Cada AdmissionCheckController verifica suas respectivas entradas em admissionChecks. Quando uma verificação é aprovada, o controlador defina o state correspondente em admissionChecks como Ready. Assim que todos os AdmissionChecks atingem o estado Ready, a QueueUnit passa para o estado Dequeued.

apiVersion: scheduling.x-k8s.io/v1alpha1
kind: QueueUnit
metadata:
  ...
spec:
  ...
status:
  admissionChecks:
  - lastTransitionTime: "2025-01-17T01:47:58Z"
    message: Succeeded
    name: sample-prov
    state: Ready
  lastUpdateTime: "2025-01-17T01:50:45Z"
  message: Dequeued
  phase: Dequeued
  podState:
    pending: 1

Configuração do AdmissionCheck

Detalhes da configuração

O administrador deve configure os seguintes componentes no cluster.

Um controlador: um AdmissionCheckController (ACController) personalizado.

O AdmissionCheckController é um controlador mantido por você para executar verificações personalizadas. Ao monitorar o campo admissionChecks no status de uma QueueUnit, o controlador identifica as QueueUnits que exigem verificação personalizada. Para determinar se é necessário verificar uma entrada admissionChecks, inspecione o campo controllerName no AdmissionCheck correspondente ao name presente no campo admissionChecks do status da QueueUnit. Após concluir a verificação, o controlador atualiza o status da entrada admissionChecks correspondente no status da QueueUnit para Ready ou Rejected, dependendo do resultado.

Duas Definições de Recurso Personalizado (CRDs):

AdmissionCheck

Essa CRD é instale automaticamente com o ACK Kube Queue. Para definir a lógica de verificação personalizada, envie um recurso personalizado (CR) que especifique o controlador responsável pela verificação e referencie seus parâmetros.

O exemplo a seguir mostra um manifesto AdmissionCheck e seus campos disponíveis.

apiVersion: kueue.x-k8s.io/v1beta1
kind: AdmissionCheck
metadata:
  name: sample-prov
spec:
  controllerName: provisioning-request-admission-controller
  parameters:
    apiGroup: kueue.x-k8s.io
    kind: ProvisioningRequestConfig
    name: prov-test-config

Parâmetro	Tipo	Descrição
`controllerName`	string	Especifica o nome do controlador que observa e processa esta verificação de admissão.
`parameters`	struct	Um tipo struct composto pelos três campos de string `apiGroup`, `kind` e `name`, que descrevem os parâmetros associados ao AdmissionCheck.

Parâmetros de verificação personalizados

Um recurso AdmissionCheck utiliza o campo parameters para referenciar um objeto de parâmetros personalizados. O controlador lê esses parâmetros para executar lógicas específicas de verificação. Ao usar parâmetros distintos para cada verificação, um único controlador pode realizar diferentes tipos de checagem. É obrigatório instale a CRD e envie o CR correspondente aos parâmetros personalizados.

Um item de configuração na fila:

Após implantar o AdmissionCheckController, o AdmissionCheck e os parâmetros personalizados, o cluster estará pronto para executar verificações personalizadas. Em seguida, ative a verificação personalizada para uma fila específica adicionando-a à configuração dessa fila.

Exemplo de configuração

Este exemplo demonstra como configure um AdmissionCheck usando o ProvisioningRequestAdmissionCheckController.

1. Ativar o controlador ProvisioningRequestAdmissionCheck

O ProvisioningRequestAdmissionCheckController é um controlador fornecido pelo ACK Kube Queue que opera em conjunto com o ProvisioningRequest. Para ative o ProvisioningRequestAdmissionCheck, defina .Values.admissionCheckController.enabled como true durante a instalação do chart Helm do ACK Kube Queue. Uma vez ativado, o ProvisioningRequestAdmissionCheckController é implantado automaticamente.

# Chart Url: https://aliacs-app-catalog.oss-cn-hangzhou.aliyuncs.com/charts-incubator/ack-kube-queue-1.22.4.tgz
admissionCheckController:
  enabled: true  # Set to true to enable ProvisioningRequestAdmissionCheck
  image:
    repository: acs/prevreq-controller
    tag: v1.0.0-aliyun-d31082a1
burst: 50
controller:
  defaultPreemptible: true
  enableBlockingMode: false
  enableStrictPriority: false
  image:
    repository: acs/kube-queue
    tag: v0.11.1-aliyun-34b259af
  queueGroupPlugin: elasticquota
  resources:
    # ...

2. Usar o controlador em um AdmissionCheck

Para utilizar o ProvisioningRequestAdmissionCheckController, envie um AdmissionCheck conforme o exemplo abaixo e defina o controllerName do AdmissionCheck como provisioning-request-admission-controller.

apiVersion: kueue.x-k8s.io/v1beta1
kind: AdmissionCheck
metadata:
  name: sample-prov
spec:
  controllerName: provisioning-request-admission-controller
  parameters:
    apiGroup: kueue.x-k8s.io
    kind: ProvisioningRequestConfig
    name: prov-test-config

3. Definir parâmetros com ProvisioningRequestConfig

O controlador ProvisioningRequestAdmissionCheck utiliza um ProvisioningRequestConfig para definir parâmetros de verificação personalizados. O manifesto a seguir exibe os campos disponíveis.

apiVersion: kueue.x-k8s.io/v1beta1
kind: ProvisioningRequestConfig
metadata:
  name: prov-test-config
spec:
  provisioningClassName: atomic-scale-up.kubernetes.io
  parameters:
  managedResources:
  - nvidia.com/gpu

Parâmetro	Tipo	Descrição
`provisioningClassName`	string	Durante a criação de um `provisioningRequest`, este valor é copiado para o campo `ProvisioningClass` do `provisioningRequest`.
`parameters`	map[string]string	Copiado para o campo `Parameters` do `provisioningRequest` quando o `provisioningRequest` é criado.
`managedResources`	[]string	Caso uma QueueUnit contenha este campo, um `provisioningRequest` será criado para ela. Caso contrário, seu `state` é definido diretamente como `Ready`.

4. Adicionar o AdmissionCheck a uma fila

Adicione verificações à configuração da fila no campo admissionChecks. Veja um exemplo abaixo.

apiVersion: scheduling.x-k8s.io/v1alpha1
kind: Queue
metadata:
  name: example-queue # Replace with the name of the queue where you want to enable the AdmissionCheck
  namespace: kube-queue
spec:
  ...
  admissionChecks:
  - name: sample-prov # Specify the name of the AdmissionCheck you created earlier
    selector: # A metav1.LabelSelector. Only QueueUnits that match this selector undergo the custom check.
      matchLabels:
        app: gpu