Repository: kubernetes
Issue: Missing details in nodeAffinity's API specification
Labels: kind/bug,sig/scheduling,sig/docs,needs-triage

### What happened?

> Orinigal issue: https://github.com/kubernetes/kubernetes/issues/126531
> This issue is re-created here instead of in `kubernetes/website` because the API specification in `kubernetes/kubernetes` needs to be fixed.

The `pod.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms.matchFields` is introduced in PR [#62202](https://github.com/kubernetes/kubernetes/pull/62002) and used to bind a pod directly to nodes via `metadata.name`. However, we discovered some hidden constraints on this field that are not documented in the API specification.

More concretely, the current API specification only says that
```
> kubectl explain pod.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms.matchFields
    KIND:       Pod
    VERSION:    v1

    FIELD: matchFields <[]NodeSelectorRequirement>


    DESCRIPTION:
        A list of node selector requirements by node's fields.
        A node selector requirement is a selector that contains values, a key, and
        an operator that relates the key and values.
    
    FIELDS:
      key   <string> -required-
        The label key that the selector applies to.
    
      operator      <string> -required-
      enum: DoesNotExist, Exists, Gt, In, ....
        Represents a key's relationship to a set of values. Valid operators are In,
        NotIn, Exists, DoesNotExist. Gt, and Lt.
    
        Possible enum values:
         - `"DoesNotExist"`
         - `"Exists"`
         - `"Gt"`
         - `"In"`
         - `"Lt"`
         - `"NotIn"`
    
      values        <[]string>
        An array of string values. If the operator is In or NotIn, the values array
        must be non-empty. If the operator is Exists or DoesNotExist, the values
        array must be empty. If the operator is Gt or Lt, the values array must have
        a single element, which will be interpreted as an integer. This array is
        replaced during a strategic merge patch.
```
**This does not specify that its key must be `metadata.name`, its operator must be `In` or `NotIn`, and the number of its values must be exactly one (though the term itself can be defined multiple times in `nodeSelectorTerms`)**

**And, the value in values must match this regex expression: `[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)`**

>Invalid value: \"f-RohHl\": a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')]

This issue has also caused confusion in [#115980](https://github.com/kubernetes/kubernetes/issues/115980), [#81725](https://github.com/kubernetes/kubernetes/issues/81725), [#78238](https://github.com/kubernetes/kubernetes/issues/78238) and a reddit [thread](https://stackoverflow.com/questions/67018171/kubernetes-what-are-valid-node-fields)



### What did you expect to happen?

The hidden constraints should be explicitly documented in the API specification.

### How can we reproduce it (as minimally and precisely as possible)?

Read the output of `kubectl describe` and the API specification.

### Anything else we need to know?

/sig docs scheduling

### Kubernetes version

Since 1.11, exists in 1.30

### Cloud provider

<details>

</details>


### OS version

<details>

```console
# On Linux:
$ cat /etc/os-release
# paste output here
$ uname -a
# paste output here

# On Windows:
C:\> wmic os get Caption, Version, BuildNumber, OSArchitecture
# paste output here
```

</details>


### Install tools

<details>

</details>


### Container runtime (CRI) and version (if applicable)

<details>

</details>


### Related plugins (CNI, CSI, ...) and versions (if applicable)

<details>

</details>