What happened?

Based on the concept of resizePolicy, it is expected behavior that resizePolicy cannot be assigned to ephemeral containers, as they do not support resource requests or limits.

However, in the Kubernetes v1.31 API documentation, there is no clear indication that the resizePolicy option is disallowed for ephemeral containers, which may lead to confusion for users.

pkg/apis/core/validation/validation_test.go

func TestValidateEphemeralContainers(t *testing.T) {
...
...
...
	{
			"Container uses disallowed field: ResizePolicy",
			line(),
			[]core.EphemeralContainer{{
				EphemeralContainerCommon: core.EphemeralContainerCommon{
					Name:                     "resources-resize-policy",
					Image:                    "image",
					ImagePullPolicy:          "IfNotPresent",
					TerminationMessagePolicy: "File",
					ResizePolicy: []core.ContainerResizePolicy{
						{ResourceName: "cpu", RestartPolicy: "NotRequired"},
					},
				},
			}},
			field.ErrorList{{Type: field.ErrorTypeForbidden, Field: "ephemeralContainers[0].resizePolicy"}},
		}
	...
	...
	...

As shown in the code above, it is explicitly stated that resizePolicy cannot be assigned to ephemeral containers.
This restriction is not reflected in the API documentation, potentially leading users to believe they can apply resizePolicy to ephemeral containers. Including this limitation in the documentation would improve clarity and enhance the user experience.

What did you expect to happen?

The Kubernetes v1.31 API documentation should clearly state that resizePolicy cannot be assigned to ephemeral containers, as they do not support resource requests or limits. This clarification would prevent users from mistakenly assuming that resizePolicy can be applied to ephemeral containers and help avoid configuration errors.

How can we reproduce it (as minimally and precisely as possible)?

1. Go to the Kubernetes v1.31 API documentation.
2. Navigate to the section discussing resizePolicy for containers.
3. Review the documentation regarding ephemeral containers.
4. Observe that there is no mention or clarification that resizePolicy cannot be applied to ephemeral containers, leading to potential misunderstandings.

Anything else we need to know?

No response

Kubernetes version

$ kubectl version
Client Version: v1.31.1
Kustomize Version: v5.4.2
Server Version: v1.31.1

Cloud provider

OS version

# On Linux:
$ cat /etc/os-release
RETTY_NAME="Ubuntu 22.04.4 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04.4 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy

$ uname -a
Linux masternode-virtual-machine 6.8.0-47-generic #47~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Wed Oct  2 16:16:55 UTC 2 x86_64 x86_64 x86_64 GNU/Linux

Install tools

Container runtime (CRI) and version (if applicable)

Related plugins (CNI, CSI, ...) and versions (if applicable)