Labels and Annotations

This page serves as a reference for all labels and annotations in Kueue.

kueue.x-k8s.io/admission-gated-by

Type: Annotation

Example: kueue.x-k8s.io/admission-gated-by: "example.com/mygate,example.com/mygate2"

Used on: Kueue-managed Jobs.

This annotation requires the AdmissionGatedBy feature that is disabled by default.

When it contains a value, the annotation prevents the Job from entering the Quota Reservation phase of Kueue’s Admission Flow. The annotation value is a comma-separated list of 1 or more gate names and can only be added during Job creation. After creation, the annotation may only be deleted or modified to remove 1 or more gates.

kueue.x-k8s.io/cluster-queue-name

Type: Label

Example: kueue.x-k8s.io/cluster-queue-name: "my-cluster-queue"

Used on: Pods.

This label requires AssignQueueLabelsForPods feature that is enabled by default.

The label key in all Pods created by Kueue workloads or managed by Kueue. It indicates which cluster queue admitted the Kueue workload that the Pod corresponds to. It can be used, for example to aggregate the actual resource usage (cpu/mem) coming from workloads admitted to a given cluster queue.

kueue.x-k8s.io/component-workload-index

Type: Annotation

Example: kueue.x-k8s.io/component-workload-index: "0"

Used on: Workload.

The annotation stores the numeric index for component workloads created by multi-workload jobs (e.g., LeaderWorkerSet creates one workload per replica). Used by MultiKueue to determine primary workload ordering when dispatching component workloads to worker clusters atomically.

kueue.x-k8s.io/is-group-workload

Type: Annotation

Example: kueue.x-k8s.io/is-group-workload: "true"

Used on: Workload.

The annotation key indicates that this workload is used for a group of Pods.

kueue.x-k8s.io/job-completions-equal-parallelism

Type: Annotation

Example: kueue.x-k8s.io/job-completions-equal-parallelism: "true"

Used on: batch/Job.

The annotation key is used to keep completions and parallelism in sync.

kueue.x-k8s.io/job-min-parallelism

Type: Annotation

Example: kueue.x-k8s.io/job-min-parallelism: "5"

Used on: batch/Job.

The annotation key indicates the minimum parallelism acceptable for the job in the case of partial admission.

kueue.x-k8s.io/job-owner-gvk

Type: Annotation

Example: kueue.x-k8s.io/job-owner-gvk: "leaderworkerset.x-k8s.io/v1, Kind=LeaderWorkerSet"

Used on: Workload.

The annotation holds the GVK (GroupVersionKind) of the owner job. Used for MultiKueue adapter lookup in workloads with multiple owner references (e.g., LeaderWorkerSet). This is an annotation rather than a label because the GVK string format contains characters invalid in label values.

kueue.x-k8s.io/job-owner-name

Type: Annotation

Example: kueue.x-k8s.io/job-owner-name: "my-leaderworkerset"

Used on: Workload.

The annotation holds the name of the owner job. Used when the owner reference has been removed by Kubernetes garbage collection but the job name is still needed for MultiKueue operations.

kueue.x-k8s.io/job-uid

Type: Label

Example: kueue.x-k8s.io/job-uid: "46ef6b23-a7d9-42b1-b0f8-071bbb29a94d"

Used on: Workload.

The label key in the workload resource holds the UID of the owner job.

kueue.x-k8s.io/local-queue-name

Type: Label

Example: kueue.x-k8s.io/local-queue-name: "my-local-queue"

Used on: Pods.

This label requires AssignQueueLabelsForPods feature that is enabled by default.

The label key in all Pods created by Kueue workloads or managed by Kueue. It indicates to which local queue a workload corresponding to the Pod has been assigned. In the case of managed Pods, the value is equal to the name of the local queue to which the Pod has been assigned.

It can be used, for example to aggregate the actual resource usage (cpu/mem) coming from workloads assigned to a given local queue.

kueue.x-k8s.io/managed

Type: Label

Example: kueue.x-k8s.io/managed: "true"

Used on: Plain Pods and ProvisioningRequest.

The label key that indicates which Pods and ProvisioningRequests are managed by Kueue.

kueue.x-k8s.io/max-exec-time-seconds

Type: Label

Example: kueue.x-k8s.io/max-exec-time-seconds: "120"

Used on: Kueue-managed Jobs.

The value of this label is passed in the Job’s Workload spec.maximumExecutionTimeSeconds and used by the Maximum execution time feature.

kueue.x-k8s.io/multikueue-origin

Type: Label

Example: kueue.x-k8s.io/multikueue-origin: "true"

Used on: MultiKueue.

The label key is used to track the creator of MultiKueue remote objects in Worker Cluster.

kueue.x-k8s.io/multikueue-origin-uid

Type: Annotation

Example: kueue.x-k8s.io/multikueue-origin-uid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Used on: MultiKueue.

The annotation stores the UID of the original object from the management cluster on remote objects in worker clusters. Used by job types (e.g., LeaderWorkerSet) that generate workload names based on their UID, ensuring workload names match between management and worker clusters.

kueue.x-k8s.io/pod-group-fast-admission

Type: Annotation

Example: kueue.x-k8s.io/pod-group-fast-admission: "true"

Used on: Plain Pods.

The annotation key is used to allow admitting a PodGroup as soon as the first Pod in the group is created.

kueue.x-k8s.io/pod-group-name

Type: Label

Example: kueue.x-k8s.io/pod-group-name: "my-pod-group-name"

Used on: Plain Pods.

The label key indicates the name of the group of Pods that should be admitted together.

kueue.x-k8s.io/pod-group-pod-index

Type: Label

Example: kueue.x-k8s.io/pod-group-pod-index: "0"

Used on: Plain Pods.

The label key indicates the Pod’s index within the Pod group it belongs to.

kueue.x-k8s.io/pod-group-pod-index-label

Type: Annotation

Example: kueue.x-k8s.io/pod-group-pod-index-label: "apps.kubernetes.io/pod-index"

Used on: Plain Pods.

The annotation key indicates a label name used to retrieve the Pod’s index within the group.

kueue.x-k8s.io/pod-group-serving

Type: Annotation

Example: kueue.x-k8s.io/pod-group-serving: "true"

Used on: Plain Pods.

The annotation key is used to indicate whether the Pod group is being used as a serving workload.

kueue.x-k8s.io/pod-group-total-count

Type: Annotation

Example: kueue.x-k8s.io/pod-group-total-count: "2"

Used on: Plain Pods.

The annotation key is used to indicate how many Pods to expect in the group.

kueue.x-k8s.io/pod-index-offset

Type: Annotation

Example: kueue.x-k8s.io/pod-index-offset: "1"

Used on: Kueue-managed Jobs (e.g., MPIJob).

The annotation indicates a starting index offset for Pod replicas within a PodSet. For example, when an MPIJob uses runLauncherAsWorker mode, Worker replica indexes start from 1 instead of 0. This annotation is set by the Kueue webhook and used by the TAS topology ungater to correctly map Pod indexes to topology assignments.

kueue.x-k8s.io/pod-suspending-parent

Type: Annotation

Example: kueue.x-k8s.io/pod-suspending-parent: "deployment"

Used on: Plain Pods.

The annotation key is used to indicate the integration name of the Pod owner.

kueue.x-k8s.io/podset

Type: Label

Example: kueue.x-k8s.io/podset: "main"

Used on: Kueue-managed Jobs.

The label key is used on the Job’s PodTemplate to indicate the name of the PodSet of the admitted Workload corresponding to the PodTemplate. The label is set when starting the Job, and removed on stopping the Job.

kueue.x-k8s.io/prebuilt-workload-name

Type: Label

Example: kueue.x-k8s.io/prebuilt-workload-name: "my-prebuilt-workload-name"

Used on: Kueue-managed Jobs.

The label key of the job holds the name of the pre-built workload to be used. The intended use of prebuilt workload is to create the Job once the workload is created. In other scenarios the behavior is undefined.

kueue.x-k8s.io/priority-boost

Type: Annotation

Example: kueue.x-k8s.io/priority-boost: "10"

Used on: Workload.

可选的有符号整数注解，用于调整工作负载的有效优先级： effectivePriority = workloadPriority + priorityBoost。 正值提高优先级，负值降低优先级。 有效优先级同时用于调度排序和抢占候选排序。 此注解由外部控制器直接设置在 Workload 上（不从 Job 传播）。 如果值缺失或非法，会按 0 处理。

kueue.x-k8s.io/priority-class

Type: Label

Example: kueue.x-k8s.io/priority-class: "my-priority-class-name"

Used on: Kueue-managed Jobs.

The label key in the workload holds the workloadPriorityClass name. This label is always mutable, as it may be useful for preemption. For more details, see Workload Priority Class.

kueue.x-k8s.io/queue-name

Type: Label

Example: kueue.x-k8s.io/queue-name: "my-local-queue"

Used on: Kueue-managed Jobs.

The label key in the workload holds the queue name.

kueue.x-k8s.io/retriable-in-group

Type: Annotation

Example: kueue.x-k8s.io/retriable-in-group: "false"

Used on: Plain Pods.

The annotation key is used to finalize the group if at least one terminated Pod (either Failed or Succeeded) has the retriable-in-group: false annotation.

kueue.x-k8s.io/role-hash

Type: Annotation

Example: kueue.x-k8s.io/role-hash: "b54683bb"

Used on: Plain Pods.

The annotation key is used as the name for a Workload podSet.