{{< feature-state feature_gate_name="TopologyAwareWorkloadScheduling" >}}

Placement scheduling algorithm is an alternative PodGroup scheduling algorithm, which uses

[scheduling plugins](/docs/reference/scheduling/config/#scheduling-plugins) to find the optimal

placement for the considered PodGroup. Users can accomodate the algorithm to their specific needs

by using and configuring plugins.

The algorithm proceeds in three main phases for a given PodGroup:

Generates candidate *placements* (subsets of nodes, that are theoretically feasible for PodGroup

assignment), for example based on the PodGroup's scheduling constraints (which can be defined

in the PodGroup object).

This phase executes as extension point: `PlacementGeneratePlugin`.

Validates each proposed placement, by running a default PodGroup scheduling algorithm, to see if

the required number of Pods from the PodGroup can fit. If they can, the placement is marked as feasible.

Scores all feasible placements to select the optimal domain for the PodGroup.

This phase executes as extension point: `PlacementScorePlugin`.

{{< note >}}

This article applies to resource bin packing in context of scheduling of a single pod. For bin packing when scheduling pod groups, please read the [article about Topology-aware Scheduling](/docs/concepts/scheduling-eviction/topology-aware-scheduling/).

{{< /note >}}

title: Topology-Aware Workload Scheduling

content_type: concept

weight: 10

{{< feature-state feature_gate_name="TopologyAwareWorkloadScheduling" >}}

*Topology-Aware Scheduling* (TAS) is a [placement scheduling algorithm](/docs/concepts/scheduling-eviction/podgroup-scheduling/#placement-scheduling-algorithm)

that allows to find the optimal placement for the considered PodGroup, guaranteeing that all pods

will be collocated within the same topology domain. Users can accomodate TAS to their specific

needs by changing TAS plugins configuration.

The scheduler includes new and extended in-tree plugins that implement the TAS extension points:

* `TopologyPlacement`: Implements the `PlacementGeneratePlugin` interface. It generates candidate

placements by grouping nodes based on the distinct values of the requested topology `key` (defined

in the PodGroup).

* `NodeResourcesFit`: Extended to implement the `PlacementScorePlugin` interface. Following

similar logic to standard pod bin-packing, it scores placements based on the allocation ratio

across all nodes within the placement. It uses the `MostAllocated` strategy to maximize resource

utilization within a placement, and it inherits resource weights from the standard pod-by-pod

plugin settings.

* `PodGroupPodsCount`: Implements the `PlacementScorePlugin` interface. It scores candidate

placements based on the total number of pods in the PodGroup that you can successfully schedule.

By default, the `NodeResourcesFit` and `PodGroupPodsCount` plugins are configured with equal

weights (both default to 1) to maintain a good balance between bin-packing logic and scheduling as

many pods as possible.

You can adjust these weights, or the resource weights in the bin-packing strategy in your

KubeSchedulerConfiguration. Here is an example snippet showing how to change the weights for both

plugins, and how to override the `NodeResourcesFit` resource weights. The latter change will apply

both to pod-by-pod and placement scoring algorithms:

apiVersion: kubescheduler.config.k8s.io/v1

kind: KubeSchedulerConfiguration

profiles:

- schedulerName: default-scheduler

plugins:

placementScore:

enabled:

# 1) Change the default weights of the placement score plugins

- name: NodeResourcesFit

weight: 2

- name: PodGroupPodsCount

weight: 5

pluginConfig:

- name: NodeResourcesFit

args:

# 2) Changing the scoring resource weights for both pod-by-pod and placement scoring

# algorithms

scoringStrategy:

# The type will only be considered in pod-by-pod scheduling. Placement scoring always

# uses MostAllocated strategy

type: LeastAllocated

# Resource weights will be used in both pod-by-pod and placement scoring algorithms

resources:

- name: cpu

weight: 2

- name: memory

weight: 3

TAS ensures that all pods within a PodGroup are co-located into a specific topology domain,

`minCount` pods can fit together into the same topology domain before committing resources.

are recreated), the scheduler will force all new incoming pods to land on the exact same topology

Every PodGroup (or PodGroupTemplate) may optionally declare the `schedulingConstraints` field,

which is interpreted by the [placement-based PodGroup scheduling algorithm](/docs/concepts/scheduling-eviction/podgroup-scheduling/#placement-scheduling-algorithm).

If constraints are defined in PodGroupTemplate, they will be copied to referencing PodGroups.

As of Kubernetes v1.36, the API supports topology constraints.

As of Kubernetes v1.36, you can specify only a single topology constraint in each PodGroup.

a Kubernetes node label, representing the target topology domain (for example, a rack or a zone).

The scheduler strictly enforces that all pods within the PodGroup are placed onto nodes that share

the exact same value for this specified label.

- key: topology.example.com/rack

1. `placementGenerate`: These plugins generate potential placements (sets of

nodes) where a considered PodGroup could be scheduled. This extension point

is only applicable to PodGroup scheduling and requires Workload scheduling

to be enabled.

1. `placementScore`: These plugins score the placements proposed by

`placementGenerate`, to pick the optimal placement for the considered

PodGroup.

- `NodeResourcesFit`: For pod-by-pod scheduling checks if the node has all

the resources that the Pod is requesting. The score can use one of three

strategies: `LeastAllocated` (default), `MostAllocated` and

`RequestedToCapacityRatio`.

For PodGroup scheduling calculates the resource utilization in the entire evaluated placement.

The score uses the `MostAllocated` strategy.

Extension points: `preFilter`, `filter`, `score`, `placementScore`.

- `TopologyPlacement`: Provides the default placement generation mechanism for PodGroup's topology

constraints.

Extension points: `placementGenerate`.

- `PodGroupPodsCount`: Provides the placement scoring algorithm based on the number of pods that

can be scheduled in the given placement.

Extension points: `placementScore`.