Missing description in the podAffinity concept documentation

[scheduler-tester]

This is a Bug Report

Problem:

We noticed some information is missing in the concept documentation about how existing pods' podAffinity/podAntiAffinity fields affect the scheduling decision for each incoming pod. This makes it difficult to understand how the scheduler respects different affinity rules when making scheduling decisions.

In detail, there're two types of pod affinity rules, namely podAffnity and podAntiAffinity, and within each type, there are requiredDuringSchedulingIgnoredDuringExecution and preferredDuringSchedulingIgnoredDuringExecution. So, each pod has in total four fields for pod affinity rules:

1. podAffinity.requiredDuringSchedulingIgnoredDuringExecution
2. podAffinity.preferredDuringSchedulingIgnoredDuringExecution
3. podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution
4. podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution

By reading the code we found that the scheduler also needs to consider such fields of existing pods in the cluster when making the decision for each incoming pod:

1. Consider the following as hard constraints and try to filter out nodes based on them:
   • incoming pod's podAffinity.requiredDuringSchedulingIgnoredDuringExecution
   • incoming pod's podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution
   • existing pods podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution
2. Consider the following as soft constraints and try to score nodes based on them:
   • incoming pod's podAffinity.preferredDuringSchedulingIgnoredDuringExecution
   • incoming pod's podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution
   • existing pods' podAffinity.requiredDuringSchedulingIgnoredDuringExecution
3. Ignore the following fields:
   • existing pods' podAffinity.preferredDuringSchedulingIgnoredDuringExecution
   • existing pods' podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution

However, the documentation does not mention how the existing pods' podAffinity and podAntiAffinity affect the scheduling decision.

Proposed Solution:
We suggest to add the following information to the concept documentation, and also the API specification:

• existing pods' podAffinity/podAntiAffinity's required parts will also be considered when scheduling.
• existing pods' podAntiAffinity's required part will be considered as hard constraints, and nodes will be filtered out if not matching this.
• existing pods' podAffinity's required part will be considered as soft constraints, and nodes will be scored based this.
• existing pods' podAffinity/podAntiAffinity's preferred parts will not be considered when scheduling.

Page to Update:
https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity
https://github.com/kubernetes/website/blob/main/content/en/docs/concepts/scheduling-eviction/assign-pod-node.md

/sig scheduling docs
/language en

[katcosgrove]

/triage accepted
/priority important-longterm

[aryasoni98]

/assign