sigs.k8s.io/kueue@v0.6.2/site/content/en/docs/concepts/admission_check.md (about)

     1  ---
     2  title: "Admission Check"
     3  date: 2023-10-05
     4  weight: 6
     5  description: >
     6    A mechanism allowing internal or external components to influence the timing of
     7    workloads admission.
     8  ---
     9  
    10  AdmissionChecks are a mechanism that allows Kueue to consider additional criteria before admitting a Workload.
    11  When a ClusterQueue has AdmissionChecks configured, each of the checks has to provide a
    12  positive signal to the Workload before it can be [Admitted](https://kueue.sigs.k8s.io/docs/concepts#admission).
    13  
    14  ## Components
    15  
    16  You can configure the mechanism using the following components:
    17  
    18  ### Admission Check
    19  
    20  Admission check is a non-namespaced API object used to define details about an `AdmissionCheck` like:
    21  
    22  - **controllerName** - It's an identifier for the controller that processes this AdmissionCheck, not necessarily a Kubernetes Pod or Deployment name. Cannot be empty.
    23  - **retryDelayMinutes** - Specifies how long to keep the workload suspended after a failed check (after it transitioned to False). After that the check state goes to "Unknown". The default is 15 min.
    24  - **parameters** - Identifies an additional resource providing additional parameters for the check.
    25  
    26  An AdmissionCheck object looks like the following:
    27  ```yaml
    28  apiVersion: kueue.x-k8s.io/v1beta1
    29  kind: AdmissionCheck
    30  metadata:
    31    name: prov-test
    32  spec:
    33    controllerName: kueue.x-k8s.io/provisioning-request
    34    retryDelayMinutes: 15
    35    parameters:
    36      apiGroup: kueue.x-k8s.io
    37      kind: ProvisioningRequestConfig
    38      name: prov-test-config
    39  ```
    40  
    41  ### ClusterQueue admissionChecks
    42  
    43  Once defined, an AdmissionCheck can be referenced in the ClusterQueues' spec. All Workloads associated with the queue need to be evaluated by the AdmissionCheck's controller before being admitted.
    44  Similarly to `ResourceFlavors`, if an `AdmissionCheck` is not found or its controller has not marked it as `Active`, the ClusterQueue will be marked as Inactive.
    45  
    46  ### AdmissionCheckState
    47  
    48  AdmissionCheckState is the way the state of an AdmissionCkeck for a specific Workload is tracked.
    49  
    50  AdmissionCheckStates are listed in the Workload's `.status.admissionCheckStates` field.
    51  
    52  The status of a Workload that has pending AdmissionChecks looks like the following:
    53  ```yaml
    54  status:
    55    admission:
    56      <...>
    57    admissionChecks:
    58    - lastTransitionTime: "2023-10-20T06:40:14Z"
    59      message: ""
    60      name: sample-prov
    61      podSetUpdates:
    62      - annotations:
    63          cluster-autoscaler.kubernetes.io/consume-provisioning-request: job-prov-job-9815b-sample-prov
    64        name: main
    65      state: Ready
    66    <...>
    67  ```
    68  
    69  A list of states being maintained in the Status of all the monitored Workloads.
    70  
    71  Kueue ensures that the list of the Workloads AdmissionCheckStates is in sync with the list of its associated ClusterQueue, Kueue adds new checks with the `Pending` state.
    72  
    73  - Once a workload has QuotaReservation and all its AdmissionChecks are in "Ready" state it will become Admitted.
    74  - If at least one of the Workloads AdmissionCheck is in the `Retry` state.
    75    - If `Admitted` the workload is evicted.
    76    - If the workload has `QuotaReservation` it will be release released.
    77  - If at least one of the Workloads AdmissionCheck is in the `Rejected`:
    78    - If `Admitted` the workload is evicted.
    79    - If the workload has `QuotaReservation` it will be release released.
    80    - The workload is marked as 'Finished' with a relevant failure message.
    81  
    82  ### Admission Check Controller
    83  
    84  Is a component that monitors Workloads maintaining the content of its specific `admissionCheckStates` and the `Active` condition of the AdmissionChecks it's  controlling.
    85  The logic for how an AdmissionCheck changes states is not part of Kueue.
    86  
    87  ## What's next?
    88  
    89  - Read the [API reference](/docs/reference/kueue.v1beta1/#kueue-x-k8s-io-v1beta1-AdmissionCheck) for `AdmissionCheck`