PodGroup API [page]deterministic

concepts

A PodGroup is a runtime object that represents a group of Pods scheduled together as a single unit. While the [Workload API](/docs/concepts/workloads/workload-api/) defines scheduling policy templates, PodGroups are the runtime counterparts that carry both the policy and the scheduling status for a specific instance of that group.

## What is a PodGroup?

The PodGroup API resource is part of the `scheduling.k8s.io/v1alpha2` [API group](#gloss:api-group) and your cluster must have that API group enabled, as well as the `GenericWorkload` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/), before you can use this API.

A PodGroup is a self-contained scheduling unit. It defines the group of Pods that should be scheduled together, carries the scheduling policy that governs placement, and records the runtime status of that scheduling decision.

## API structure

A PodGroup consists of a `spec` that defines the desired scheduling behavior and a `status` that reflects the current scheduling state.

### Scheduling policy

Each PodGroup carries a [scheduling policy](/docs/concepts/workloads/workload-api/policies/) (`basic` or `gang`) in `spec.schedulingPolicy`. When a workload controller creates the PodGroup, this policy is copied from the Workload's PodGroupTemplate at creation time. For standalone PodGroups, you set the policy directly.

```yaml spec: schedulingPolicy: gang: minCount: 4 ```

### Template reference

The optional `spec.podGroupTemplateRef` links the PodGroup back to the PodGroupTemplate in the Workload it was created from. This is useful for observability and tooling.

```yaml spec: podGroupTemplateRef: workload: workloadName: training-policy podGroupTemplateName: worker ```

### Requesting DRA devices for a PodGroup

[Devices](#gloss:device) available through [Dynamic Resource Allocation (DRA)](#gloss:dra) can be requested by a PodGroup through its `spec.resourceClaims` field:

```yaml apiVersion: scheduling.k8s.io/v1alpha2 kind: PodGroup metadata: name: training-group namespace: some-ns spec: ... resourceClaims: - name: pg-claim resourceClaimName: my-pg-claim - name: pg-claim-template resourceClaimTemplateName: my-pg-template ```

[ResourceClaims](#gloss:resourceclaim) associated with PodGroups can be shared by all Pods belonging to the group. With only a reference to the PodGroup in the ResourceClaim's `status.reservedFor` instead of each individual Pod, any number of Pods in the same PodGroup can share a ResourceClaim. ResourceClaims can also be generated from [ResourceClaimTemplates](#gloss:resourceclaimtemplate) for each PodGroup, allowing the devices allocated to each generated ResourceClaim to be shared by the Pods in each PodGroup.

For more details and a more complete example, see the [DRA documentation](/docs/concepts/scheduling-eviction/dynamic-resource-allocation/#workload-resource-claims).

### Status

The scheduler updates `status.conditions` to report whether the group has been successfully scheduled. The primary condition is `PodGroupScheduled`, which is `True` when all required Pods have been placed and `False` when scheduling fails.

> Note: The `PodGroupScheduled` condition reflects the initial scheduling decision only. The scheduler does not update it if Pods later fail or are evicted. See [Limitations](/docs/concepts/workloads/podgroup-api/lifecycle/#limitations) for details.

See the [PodGroup lifecycle](/docs/concepts/workloads/podgroup-api/lifecycle/#podgroup-status) page for the full list of conditions and reasons.

## Creating a PodGroup

A PodGroup API resource is part of the `scheduling.k8s.io/v1alpha2` [API group](#gloss:api-group). (and your cluster must have that API group enabled, as well as the `GenericWorkload` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/), before you can use this API).

The following manifest creates a PodGroup with a gang scheduling policy that requir …(trimmed)

Sources

concepts/workloads/podgroup-api/_index.md · doc — “PodGroup API”

Related (15)

references API Group — API group conf=1

references Device — Devices conf=1

references Dynamic Resource Allocation — Dynamic Resource Allocation (DRA) conf=1

references ResourceClaim — ResourceClaims conf=1

references ResourceClaimTemplate — ResourceClaimTemplates conf=1

part_of What is a PodGroup? — describes conf=1

part_of API structure — describes conf=1

part_of Creating a PodGroup — describes conf=1

part_of How it fits together — describes conf=1

part_of {{% heading "whatsnext" %}} — describes conf=1

part_of Scheduling policy — describes conf=1

part_of Template reference — describes conf=1

part_of Requesting DRA devices for a PodGroup — describes conf=1

part_of Status — describes conf=1

api_for Pod — documents API object conf=1

← all Docs