<p>I cannot really understand the purpose and usage of topologyKey in pod affinity. The documentations says:</p>
<blockquote>
<p><strong>topologyKey</strong> is the key of node labels. If two Nodes are labelled with this key and have identical values for that label, the scheduler treats both Nodes as being in the same topology. The scheduler tries to place a balanced number of Pods into each topology domain.</p>
</blockquote>
<p>And example usage is as follows:</p>
<pre><code>kind: Pod
metadata:
  name: with-pod-affinity
spec:
  affinity:
    podAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
          - key: security
            operator: In
            values:
            - S1
        topologyKey: topology.kubernetes.io/zone
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
            - key: security
              operator: In
              values:
              - S2
          topologyKey: topology.kubernetes.io/zone
  containers:
  - name: with-pod-affinity
    image: k8s.gcr.io/pause:2.0
</code></pre>
<p>So where does <strong>topology.kubernetes.io/zone</strong> come from? How can I know what value should I provide for this <strong>topologyKey</strong> field in my yaml file, and what happens if I just put a random string here? Should I label my node and use the key of this label in topologyKey field?</p>
<p>Thank you.</p>

<p>Required as part of a <strong>affinity.podAffinity</strong> or <strong>affinity.podAntiAffinity</strong> <em>spec</em> section, the <strong>topologyKey</strong> field is used by the scheduler to determine the domain for Pod placement.</p>
<p>The topologyKey <em>domain</em> is used to determine relative placement of the Pods being scheduled relative to the Pods identified by the <strong>...labelSelector.matchExpressions</strong> section.</p>
<p>With <strong>podAffinity</strong>, a Pod <em>will</em> be scheduled in the same domain as the Pods that match the expression.</p>
<p>Two common label options are <strong>topology.kubernetes.io/zone</strong> and <strong>kubernetes.io/hostname</strong>.  Others can be found in the Kubernetes <a href="https://kubernetes.io/docs/reference/labels-annotations-taints/" rel="noreferrer">Well-Known Labels, Annotations and Taints</a> documentation.</p>
<ul>
<li><strong>topology.kubernetes.io/zone</strong>: Pods will be scheduled <em>in the same zone</em> as a Pod that matches the expression.</li>
<li><strong>kubernetes.io/hostname</strong>: Pods will be scheduled <em>on the same hostname</em> as a Pod that matches the expression.</li>
</ul>
<p>For <strong>podAntiAffinity</strong>, the opposite is true: Pods <em>will not</em> be scheduled in the same domain as the Pods that match the expression.</p>
<p>The Kubernetes documentation <a href="https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-as%20a%20Pod%20that%20matches%20the%20expression.node/#inter-pod-affinity-and-anti-affinity" rel="noreferrer"><strong>Assigning Pods to Nodes</strong> documentation (Inter-pod affinity and anti-affinity section)</a> provides a additional explanation.</p>
