PodGroup

PodGroup represents a runtime instance of pods grouped together. PodGroups are created by workload controllers (Job, LWS, JobSet, etc...) from Workload.podGroupTemplates. PodGroup API enablement is toggled by the GenericWorkload feature gate.

apiVersion: scheduling.k8s.io/v1alpha2

import "k8s.io/api/scheduling/v1alpha2"

PodGroup

Field	Description
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ObjectMeta	Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
`spec` * PodGroupSpec	Spec defines the desired state of the PodGroup.
`status` PodGroupStatus	Status represents the current observed state of the PodGroup.

PodGroupSpec

PodGroupSpec defines the desired state of a PodGroup.

Field	Description
`disruptionMode` string	DisruptionMode defines the mode in which a given PodGroup can be disrupted. Controllers are expected to fill this field by copying it from a PodGroupTemplate. One of Pod, PodGroup. Defaults to Pod if unset. This field is immutable. This field is available only when the WorkloadAwarePreemption feature gate is enabled. Possible enum values: - `"Pod"` means that individual pods can be disrupted or preempted independently. It doesn't depend on exact set of pods currently running in this PodGroup. - `"PodGroup"` means that the whole PodGroup needs to be disrupted or preempted together.
`podGroupTemplateRef` PodGroupTemplateReference	PodGroupTemplateRef references an optional PodGroup template within other object (e.g. Workload) that was used to create the PodGroup. This field is immutable.
`priority` integer	Priority is the value of priority of this pod group. Various system components use this field to find the priority of the pod group. When Priority Admission Controller is enabled, it prevents users from setting this field. The admission controller populates this field from PriorityClassName. The higher the value, the higher the priority. This field is immutable. This field is available only when the WorkloadAwarePreemption feature gate is enabled.
`priorityClassName` string	PriorityClassName defines the priority that should be considered when scheduling this pod group. Controllers are expected to fill this field by copying it from a PodGroupTemplate. Otherwise, it is validated and resolved similarly to the PriorityClassName on PodGroupTemplate (i.e. if no priority class is specified, admission control can set this to the global default priority class if it exists. Otherwise, the pod group's priority will be zero). This field is immutable. This field is available only when the WorkloadAwarePreemption feature gate is enabled.
`resourceClaims` PodGroupResourceClaim array patch strategy: merge,retainKeys on key `name`	ResourceClaims defines which ResourceClaims may be shared among Pods in the group. Pods consume the devices allocated to a PodGroup's claim by defining a claim in its own Spec.ResourceClaims that matches the PodGroup's claim exactly. The claim must have the same name and refer to the same ResourceClaim or ResourceClaimTemplate. This is an alpha-level field and requires that the DRAWorkloadResourceClaims feature gate is enabled. This field is immutable.
`schedulingConstraints` PodGroupSchedulingConstraints	SchedulingConstraints defines optional scheduling constraints (e.g. topology) for this PodGroup. Controllers are expected to fill this field by copying it from a PodGroupTemplate. This field is immutable. This field is only available when the TopologyAwareWorkloadScheduling feature gate is enabled.
`schedulingPolicy` * PodGroupSchedulingPolicy	SchedulingPolicy defines the scheduling policy for this instance of the PodGroup. Controllers are expected to fill this field by copying it from a PodGroupTemplate. This field is immutable.

PodGroupStatus

PodGroupStatus represents information about the status of a pod group.

Field Description

conditions
Condition array
patch strategy: merge on key type Conditions represent the latest observations of the PodGroup's state. Known condition types: - "PodGroupScheduled": Indicates whether the scheduling requirement has been satisfied. - "DisruptionTarget": Indicates whether the PodGroup is about to be terminated due to disruption such as preemption. Known reasons for the PodGroupScheduled condition: - "Unschedulable": The PodGroup cannot be scheduled due to resource constraints, affinity/anti-affinity rules, or insufficient capacity for the gang. - "SchedulerError": The PodGroup cannot be scheduled due to some internal error that happened during scheduling, for example due to nodeAffinity parsing errors. Known reasons for the DisruptionTarget condition: - "PreemptionByScheduler": The PodGroup was preempted by the scheduler to make room for higher-priority PodGroups or Pods.

resourceClaimStatuses
PodGroupResourceClaimStatus array
patch strategy: merge,retainKeys on key name Status of resource claims.

Field	Description
`conditions` Condition array patch strategy: merge on key `type`	Conditions represent the latest observations of the PodGroup's state. Known condition types: - "PodGroupScheduled": Indicates whether the scheduling requirement has been satisfied. - "DisruptionTarget": Indicates whether the PodGroup is about to be terminated due to disruption such as preemption. Known reasons for the PodGroupScheduled condition: - "Unschedulable": The PodGroup cannot be scheduled due to resource constraints, affinity/anti-affinity rules, or insufficient capacity for the gang. - "SchedulerError": The PodGroup cannot be scheduled due to some internal error that happened during scheduling, for example due to nodeAffinity parsing errors. Known reasons for the DisruptionTarget condition: - "PreemptionByScheduler": The PodGroup was preempted by the scheduler to make room for higher-priority PodGroups or Pods.
`resourceClaimStatuses` PodGroupResourceClaimStatus array patch strategy: merge,retainKeys on key `name`	Status of resource claims.

PodGroupList

PodGroupList contains a list of PodGroup resources.

Field	Description
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`items` * PodGroup array	Items is the list of PodGroups.
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata` ListMeta	Standard list metadata.

BasicSchedulingPolicy

BasicSchedulingPolicy indicates that standard Kubernetes scheduling behavior should be used.

GangSchedulingPolicy

GangSchedulingPolicy defines the parameters for gang scheduling.

Field	Description
`minCount` * integer	MinCount is the minimum number of pods that must be schedulable or scheduled at the same time for the scheduler to admit the entire group. It must be a positive integer.

PodGroupResourceClaim

PodGroupResourceClaim references exactly one ResourceClaim, either directly or by naming a ResourceClaimTemplate which is then turned into a ResourceClaim for the PodGroup.

It adds a name to it that uniquely identifies the ResourceClaim inside the PodGroup. Pods that need access to the ResourceClaim define a matching reference in its own Spec.ResourceClaims. The Pod's claim must match all fields of the PodGroup's claim exactly.

Field	Description
`name` * string	Name uniquely identifies this resource claim inside the PodGroup. This must be a DNS_LABEL.
`resourceClaimName` string	ResourceClaimName is the name of a ResourceClaim object in the same namespace as this PodGroup. The ResourceClaim will be reserved for the PodGroup instead of its individual pods. Exactly one of ResourceClaimName and ResourceClaimTemplateName must be set.
`resourceClaimTemplateName` string	ResourceClaimTemplateName is the name of a ResourceClaimTemplate object in the same namespace as this PodGroup. The template will be used to create a new ResourceClaim, which will be bound to this PodGroup. When this PodGroup is deleted, the ResourceClaim will also be deleted. The PodGroup name and resource name, along with a generated component, will be used to form a unique name for the ResourceClaim, which will be recorded in podgroup.status.resourceClaimStatuses. This field is immutable and no changes will be made to the corresponding ResourceClaim by the control plane after creating the ResourceClaim. Exactly one of ResourceClaimName and ResourceClaimTemplateName must be set.

PodGroupSchedulingConstraints

PodGroupSchedulingConstraints defines scheduling constraints (e.g. topology) for a PodGroup.

Field	Description
`topology` TopologyConstraint array	Topology defines the topology constraints for the pod group. Currently only a single topology constraint can be specified. This may change in the future.

PodGroupSchedulingPolicy

PodGroupSchedulingPolicy defines the scheduling configuration for a PodGroup. Exactly one policy must be set.

Field	Description
`basic` BasicSchedulingPolicy	Basic specifies that the pods in this group should be scheduled using standard Kubernetes scheduling behavior.
`gang` GangSchedulingPolicy	Gang specifies that the pods in this group should be scheduled using all-or-nothing semantics.

PodGroupTemplateReference

PodGroupTemplateReference references a PodGroup template defined in some object (e.g. Workload). Exactly one reference must be set.

Field	Description
`workload` WorkloadPodGroupTemplateReference	Workload references the PodGroupTemplate within the Workload object that was used to create the PodGroup.

TopologyConstraint

TopologyConstraint defines a topology constraint for a PodGroup.

Field	Description
`key` * string	Key specifies the key of the node label representing the topology domain. All pods within the PodGroup must be colocated within the same domain instance. Different PodGroups can land on different domain instances even if they derive from the same PodGroupTemplate. Examples: "topology.kubernetes.io/rack"

WorkloadPodGroupTemplateReference

WorkloadPodGroupTemplateReference references the PodGroupTemplate within the Workload object.

Field	Description
`podGroupTemplateName` * string	PodGroupTemplateName defines the PodGroupTemplate name within the Workload object.
`workloadName` * string	WorkloadName defines the name of the Workload object.

© 2026 The Kubernetes Authors | Documentation Distributed under CC BY 4.0
Copyright © 2026 The Linux Foundation ®. All rights reserved.
https://kubernetes.io/docs/reference/kubernetes-api/scheduling/pod-group-v1alpha2/