diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 2500db659e05a..d2ba70d53ae11 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -180,7 +180,8 @@ different Kubernetes components. | `RotateKubeletServerCertificate` | `true` | Beta | 1.12 | | | `SeccompDefault` | `false` | Alpha | 1.22 | 1.24 | | `SeccompDefault` | `true` | Beta | 1.25 | | -| `ServerSideFieldValidation` | `false` | Alpha | 1.23 | - | +| `ServerSideFieldValidation` | `false` | Alpha | 1.23 | 1.24 | +| `ServerSideFieldValidation` | `true` | Beta | 1.25 | | | `ServiceInternalTrafficPolicy` | `false` | Alpha | 1.21 | 1.21 | | `ServiceInternalTrafficPolicy` | `true` | Beta | 1.22 | | | `ServiceIPStaticSubrange` | `false` | Alpha | 1.24 | | diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index e423cc408c1d6..3eee082a2868d 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -661,20 +661,25 @@ of single-resource API requests, then aggregates the responses if needed. By contrast, the Kubernetes API verbs **list** and **watch** allow getting multiple resources, and **deletecollection** allows deleting multiple resources. -## Field Validation +## Field validation - {{< feature-state for_k8s_version="v1.24" state="beta" >}} + {{< feature-state for_k8s_version="v1.25" state="beta" >}} -In certain situations, the API server will drop fields it does not recognize +Historically, in certain situations, the API server drops fields that it does not recognize from an object it receives. The two situations where this will occur are: 1. The field is unrecognized because it is not in the resource's OpenAPI schema. (One - exception to this is for CRDs that explicitly choose not to prune unknown + exception to this is for {{< glossary_tooltip + term_id="CustomResourceDefinition" text="CRDs" >}} that explicitly choose not to prune unknown fields via `x-kubernetes-preserve-unknown-fields`). 2. The field is duplicated in the object. +Provided that the `ServerSideFieldValidation` feature gate is enabled (disabled +by default in 1.23 and 1.24, enabled by default starting in 1.25), you can take +advantage of server side field validation to catch these unrecognized fields. + When you use HTTP verbs that can submit data (`POST`, `PUT`, and `PATCH`), field validation gives you the option to choose how you would like to be notified of these fields that are being dropped by the API server. Possible levels of @@ -690,8 +695,8 @@ You always receive an error response in this case, no matter what field validati ### Setting the field validation level -Field validation is set by the `fieldValidation` query parameter. This parameter -is a string, working as an enum and the only accepted values are: +Field validation is set by the `fieldValidation` query parameter. The three +values that you can provide for this parameter are: `Ignore` : The API server succeeds in handling the request as it would without the erroneous fields @@ -699,29 +704,31 @@ being set, dropping all unknown and duplicate fields and giving no indication it has done so. `Warn` -: (Default) The API server succeeds in handling the request, but will add a -warning to the warning header for each unknown/duplicate field it detects. It -uses the HTTP response header `Warning:`; see -the blog article [Warning: Helpful Warnings Ahead](/blog/2020/09/03/warnings/) for more -about API server warnings in general. +: (Default) The API server succeeds in handling the request, and reports a +warning to the client. The warning is sent using the `Warning:` response header, +adding one warning item for each unknown or duplicate field. For more +information about warnings and the Kubernetes API, see the blog article +[Warning: Helpful Warnings Ahead](/blog/2020/09/03/warnings/). `Strict` : The API server rejects the request with a 400 Bad Request error when it -detects any unknown/duplicate fields and will provide all the unknown/duplicate -fields it has detected in the response message. +detects any unknown or duplicate fields. The response message from the API +server specifies all the unknown or duplicate fields that the API server has +detected. Tools that submit requests to the server (such as `kubectl`), might set their own defaults that are different from the `Warn` validation level that the API server uses by default. -Kubectl uses the `--validate` flag to set the level of field validation. +The `kubectl` tool uses the `--validate` flag to set the level of field validation. Historically `--validate` was used to toggle client-side validation on or off as -a boolean flag. Since kubernetes 1.24, kubectl uses -server-side field validation by default, and will only fall back to client-side -validation when it cannot connect to an API server with field validaiton -enabled. It accepts the values `ignore`, `warn`, +a boolean flag. Since Kubernetes 1.25, kubectl uses +server-side field validation when sending requests to a serer with this feature +enabled. Validation will fall back to client-side only when it cannot connect +to an API server with field validation enabled. +It accepts the values `ignore`, `warn`, and `strict` while also accepting the values `true` (equivalent to `strict`) and `false` -(equivalent to `ignore`). Kubectl continues to default to `--validate=true` +(equivalent to `ignore`). The default validation setting for kubectl is `--validate=true`, which means strict server-side field validation. ## Dry-run