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

     1  ---
     2  title: "Workload Priority Class"
     3  date: 2023-10-02
     4  weight: 6
     5  description: >
     6    A priority class which value is utilized by Kueue controller and is independent from pod's priority.
     7  ---
     8  
     9  A `WorkloadPriorityClass` allows you to control the [`Workload`'s](/docs/concepts/workload) priority without affecting the pod's priority.
    10  This feature is useful for these cases:
    11  - want to prioritize workloads that remain inactive for a specific duration
    12  - want to set a lower priority for development workloads and higher priority for production workloads
    13  
    14  A sample WorkloadPriorityClass looks like the following:
    15  
    16  ```yaml
    17  apiVersion: kueue.x-k8s.io/v1beta1
    18  kind: WorkloadPriorityClass
    19  metadata:
    20    name: sample-priority
    21  value: 10000
    22  description: "Sample priority"
    23  ```
    24  
    25  `WorkloadPriorityClass` objects are cluster scoped, so they can be used by a job in any namespace.
    26  
    27  ## How to use WorkloadPriorityClass on Jobs
    28  
    29  You can specify the `WorkloadPriorityClass` by setting the label `kueue.x-k8s.io/priority-class`.
    30  
    31  ```yaml
    32  apiVersion: batch/v1
    33  kind: Job
    34  metadata:
    35    name: sample-job
    36    labels:
    37      kueue.x-k8s.io/queue-name: user-queue
    38      kueue.x-k8s.io/priority-class: sample-priority
    39  spec:
    40  ...
    41  ```
    42  
    43  Kueue generates the following `Workload` for the Job above.
    44  The `PriorityClassName` field can accept either `PriorityClass` or
    45  `WorkloadPriorityClass` name as a value. To distinguish, when using `WorkloadPriorityClass`,
    46  a `priorityClassSource` field has the `kueue.x-k8s.io/workloadpriorityclass` value.
    47  When using `PriorityClass`, a `priorityClassSource` field has the `scheduling.k8s.io/priorityclass` value.
    48  
    49  ```yaml
    50  apiVersion: kueue.x-k8s.io/v1beta1
    51  kind: Workload
    52  metadata:
    53    name: job-sample-job-7f173
    54  spec:
    55    priorityClassSource: kueue.x-k8s.io/workloadpriorityclass
    56    priorityClassName: sample-priority
    57    priority: 10000
    58    queueName: user-queue
    59  ...
    60  ```
    61  
    62  For other job frameworks, you can set `WorkloadPriorityClass` using the same label.
    63  The Following is an example of `MPIJob`.
    64  
    65  ```yaml
    66  apiVersion: kubeflow.org/v2beta1
    67  kind: MPIJob
    68  metadata:
    69    name: pi
    70    labels:
    71      kueue.x-k8s.io/queue-name: user-queue
    72      kueue.x-k8s.io/priority-class: sample-priority
    73  spec:
    74  ...
    75  ```
    76  
    77  ## The relationship between pod's priority and workload's priority
    78  
    79  When creating a `Workload` for a given job, Kueue considers the following scenarios:
    80  1. A job specifies both `WorkloadPriorityClass` and `PriorityClass`
    81  - `WorkloadPriorityClass` is used for the workload's priority.
    82  - `PriorityClass` is used for the pod's priority.
    83  2. A job specifies only `WorkloadPriorityClass`
    84  - `WorkloadPriorityClass` is used for the workload's priority.
    85  - `WorkloadPriorityClass` is not used for pod's priority.
    86  3. A job specifies only `PriorityClass`
    87  - `PriorityClass` is used for the workload's priority and pod's priority.
    88  
    89  In certain job frameworks, there are CRDs that:
    90  - Define multiple pod specs, where each can have their own pod priority, or
    91  - Define the overall pod priority in a dedicated field.
    92  By default kueue will take the PriorityClassName of the first PodSet having one set,
    93  however the integration of the CRD with Kueue can implement
    94  [`JobWithPriorityClass interface`](https://github.com/kubernetes-sigs/kueue/blob/e162f8508b503d20feb9b31fd0b27d91e58f2c2f/pkg/controller/jobframework/interface.go#L81-L84)
    95  to change this behavior. You can read the code for each job integration
    96  to learn how the priority class is obtained.
    97  
    98  ## Where workload's priority is used
    99  
   100  The priority of workloads is used for:
   101  - Sorting the workloads in the ClusterQueues.
   102  - Determining whether a workload can preempt others.
   103  
   104  ## Workload's priority values are always mutable
   105  
   106  The `Workload`'s `Priority` field is always mutable.
   107  If a `Workload` has been pending for a while, you can consider updating its priority to execute it earlier,
   108  based on your own policies.
   109  Workload's `PriorityClassSource` and `PriorityClassName` fields are immutable.
   110  
   111  ## What's next?
   112  
   113  - Learn how to [run jobs](/docs/tasks/run_jobs)
   114  - Learn how to [run jobs with workload priority](/docs/tasks/run_job_with_workload_priority)
   115  - Read the [API reference](/docs/reference/kueue.v1beta1/#kueue-x-k8s-io-v1beta1-WorkloadPriorityClass) for `WorkloadPriorityClass`