Missing clarifications for the Services .spec.ipFamiliyPolicy options (IPv4/IPv6 dual-stack documentation)

[Antonio Alonso Alarcon]

Hi k8s community,
This issue refers to the https://kubernetes.io/docs/concepts/services-networking/dual-stack/ documentation page, specifically to the "Services" chapter (link: https://kubernetes.io/docs/concepts/services-networking/dual-stack/#services).

The description of the PreferDualStack and RequireDualStack values for the Service API objects' .spec.ipFamilyPolicy field is missing relevant clarifications; here below what we have nowadays:

• PreferDualStack:
  • Allocates IPv4 and IPv6 cluster IPs for the Service.
• RequireDualStack: Allocates Service .spec.ClusterIPs from both IPv4 and IPv6 address ranges.
  • Selects the .spec.ClusterIP from the list of .spec.ClusterIPs based on the address family of the first element in the .spec.ipFamilies array.

The current text for RequireDualStack applies the same for PreferDualStack when dual-stack is enabled in a k8s cluster; the real difference between these two options is not being described. I think something as below (or whatever better wording) would work better (solving also a pair of "formatting" mistake in current text: (a) that sub-bullet for PreferDualStack description's first line that is not for the other two options' first line and (b) .spec.clusterIP/s instead of .spec.ClusterIP/s)
(note I used bold letters to remark the added text)

• PreferDualStack: Allocates IPv4 and IPv6 cluster IPs for the Service when dual-stack enabled (done as described by RequireDualStack below), falling back to single-stack behavior if dual-stack not enabled/supported.
• RequireDualStack: Allocates Service .spec.clusterIPs from both IPv4 and IPv6 address ranges when dual-stack enabled, failing to create the Service API object if dual-stack not enabled/supported
  • Selects the .spec.clusterIP from the list of .spec.clusterIPs based on the address family of the first element in the .spec.ipFamilies array.

[Dipesh Rawat]

Page reported in issue: https://kubernetes.io/docs/concepts/services-networking/dual-stack/
/language en

[Dipesh Rawat]

/sig network

[Kundan Kumar]

/triage accepted