ACK Kube Queue のカスタム AdmissionCheck の追加 - Container Service for Kubernetes

デフォルトでは、ACK Kube Queue は ElasticQuotaTree で定義されたクォータの Max 値のみをチェックします。クォータチェックが通過すると、ジョブはスケジューラによってスケジュールされます。より複雑なデキュー時のチェックロジックを実装する必要がある場合は、AdmissionCheck メカニズムを使用できます。AdmissionCheck は、ACK Kube Queue が提供するプラグイン可能なカスタムデキュー時チェックメカニズムです。これにより、ジョブがキューからデキューされる（つまり、スケジューラによってスケジュールされる）前に追加の検証やチェックを実行し、適格なジョブのみがスケジュールされることを保証します。

仕組み

新しい AdmissionCheck をクラスターに追加すると、ACK Kube Queue は QueueUnit のクォータチェック完了後にすぐにジョブのステータスを Dequeued に設定しません。代わりに、QueueUnit のステータスを Reserved に設定し、QueueUnit の status フィールドにステータスが Pending の admissionChecks を追加します。

apiVersion: scheduling.x-k8s.io/v1alpha1
kind: QueueUnit
metadata:
  ...
spec:
  ...
status:
  admissionChecks:
  - lastTransitionTime: "2025-01-17T01:46:58Z"
    message: ""
    name: sample-prov
    state: 保留中
  lastUpdateTime: "2025-01-17T01:46:58Z"
  message: リソースの予約に成功しました。承認チェックが準備完了になるのを待っています。
  phase: 予約済み
  podState: {}

各 AdmissionCheckController は自身が担当する admissionChecks をチェックし、チェックが通過した場合、admissionChecks 内の state を Ready に設定します。すべての AdmissionCheck が Ready 状態になると、QueueUnit は 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

次の図は、AdmissionCheck のワークフローを示しています。

AdmissionCheck 構成

構成の詳細

管理者は、クラスター内で以下の項目を構成する必要があります。

コントローラー：カスタム AdmissionCheckController（図中では ACController と表記）
AdmissionCheckController は、カスタムチェックを実行するためにユーザーが管理するコントローラーです。QueueUnit の status 内の admissionChecks フィールドをモニタリングすることで、どの QueueUnit に対してカスタムチェックが必要かを検出できます。コントローラーは、controllerName を確認して、特定の admissionChecks エントリのチェックを担当するかどうかを判断します。この controllerName は、QueueUnit の status 内の admissionChecks フィールドにある name に対応する AdmissionCheck オブジェクト内に記述されています。チェック完了後、コントローラーは QueueUnit の status 内の対応する admissionChecks エントリの status を、結果に応じて Ready または Rejected に更新します。

2 つのカスタムリソース定義（CRD）：

AdmissionCheck

この CRD は、ACK Kube Queue のインストール時に自動的に導入されます。カスタムチェックロジックを定義するには、カスタムリソース（CR）を送信します。この CR には、チェックを処理するコントローラーの名前および関連パラメーターが含まれます。

以下の例は、サンプルの AdmissionCheck とその利用可能なフィールドを示しています。

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

パラメーター	タイプ	説明
`controllerName`	string	この AdmissionCheck を処理するコントローラーの名前を指定します。
`parameters`	struct	`apiGroup`、`kind`、`name` の 3 つの文字列フィールドで構成される構造体です。この構造体は、AdmissionCheck に関連付けられたパラメーターを記述します。

カスタムチェックパラメーター
AdmissionCheck は parameters フィールドを使用して、カスタムパラメーターリソースを参照します。コントローラーがチェックを実行する際、これらのカスタムパラメーターを読み取り、特定のロジックを実行します。これらのカスタムパラメーター用の CRD をインストールし、対応する CR を送信する必要があります。単一のコントローラーで複数種類のチェックを実行できます。各チェックに対して異なるパラメーターを定義することで、コントローラーは異なる動作を区別できます。

キュー内の設定項目：
AdmissionCheckController、AdmissionCheck CR、およびカスタムパラメーターリソースをデプロイすると、クラスターはカスタムチェックを実行できるようになります。その後、対象のキューにチェックを追加して有効化できます。

構成例

以下は、AdmissionCheck の構成例です。この例では、ProvisioningRequestAdmissionCheckController を使用します。

手順 1：ProvisioningRequestAdmissionCheck コントローラーの有効化

ProvisioningRequestAdmissionCheckController は、ACK Kube Queue が提供する ProvisioningRequest と連携するコントローラーです。ACK Kube Queue の Helm Chart インストール時に .Values.admissionCheckController.enabled を true に設定することで、ProvisioningRequestAdmissionCheck を有効化できます。ProvisioningRequestAdmissionCheck が有効化されると、ProvisioningRequestAdmissionCheckController が自動的にデプロイされます。

手順 2：AdmissionCheck でのコントローラーの使用

ProvisioningRequestAdmissionCheckController を使用するには、以下の例のように controllerName を provisioning-request-admission-controller に設定して AdmissionCheck を送信します。

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：ProvisioningRequestConfig によるチェックパラメーターのカスタマイズ

ProvisioningRequestConfig は、ProvisioningRequestAdmissionCheckController 専用のパラメータータイプです。これを使用してチェックパラメーターをカスタマイズできます。以下の例は、サンプルの ProvisioningRequestConfig とその利用可能なフィールドを示しています。

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

パラメーター	タイプ	説明
`provisioningClassName`	string	`provisioningRequest` が作成される際、この値は `provisioningRequest` の `ProvisioningClass` フィールドにコピーされます。
`parameters`	map[string]string	`provisioningRequest` が作成される際、この値は `provisioningRequest` の `Parameters` フィールドにコピーされます。
`managedResources`	[]string	QueueUnit に指定されたリソースが含まれている場合、その QueueUnit に対して `provisioningRequest` が作成されます。そうでない場合、その `state` は直接 `Ready` に設定されます。

手順 4：キューへの AdmissionCheck 構成の追加

キュー構成の admissionChecks フィールドにチェックを追加できます。以下はその例です。

apiVersion: scheduling.x-k8s.io/v1alpha1
kind: Queue
metadata:
  name: example-queue # AdmissionCheck を有効化したいキューの名前に置き換えてください。
  namespace: kube-queue
spec:
  ...
  admissionChecks:
  - name: sample-prov # 事前に送信した AdmissionCheck の名前を指定します。
    selector: # metav1.LabelSelector。このセレクターに一致する QueueUnit のみがこのカスタムチェックの対象となります。
      matchLabels:
        app: gpu