From 8ea9d24b851f0d4f61729468947e07c09d476923 Mon Sep 17 00:00:00 2001 From: Kevin Delgado Date: Tue, 31 Jan 2023 16:58:29 +0000 Subject: [PATCH 1/2] docs for field validation GA --- .../reference/command-line-tools-reference/feature-gates.md | 5 +++-- content/en/docs/reference/using-api/api-concepts.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) 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 cf2edda03c3ce..d1132729b7b2e 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 @@ -179,8 +179,6 @@ For a reference to old feature gates that are removed, please refer to | `SELinuxMountReadWriteOncePod` | `false` | Alpha | 1.25 | | | `SeccompDefault` | `false` | Alpha | 1.22 | 1.24 | | `SeccompDefault` | `true` | Beta | 1.25 | | -| `ServerSideFieldValidation` | `false` | Alpha | 1.23 | 1.24 | -| `ServerSideFieldValidation` | `true` | Beta | 1.25 | | | `SizeMemoryBackedVolumes` | `false` | Alpha | 1.20 | 1.21 | | `SizeMemoryBackedVolumes` | `true` | Beta | 1.22 | | | `StatefulSetAutoDeletePVC` | `false` | Alpha | 1.22 | | @@ -322,6 +320,9 @@ For a reference to old feature gates that are removed, please refer to | `ServerSideApply` | `false` | Alpha | 1.14 | 1.15 | | `ServerSideApply` | `true` | Beta | 1.16 | 1.21 | | `ServerSideApply` | `true` | GA | 1.22 | - | +| `ServerSideFieldValidation` | `false` | Alpha | 1.23 | 1.24 | +| `ServerSideFieldValidation` | `true` | Beta | 1.25 | 1.26 | +| `ServerSideFieldValidation` | `true` | GA | 1.27 | - | | `ServiceInternalTrafficPolicy` | `false` | Alpha | 1.21 | 1.21 | | `ServiceInternalTrafficPolicy` | `true` | Beta | 1.22 | 1.25 | | `ServiceInternalTrafficPolicy` | `true` | GA | 1.26 | - | diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index 084b54d7f4a20..7bcae289be158 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -690,7 +690,7 @@ These situations are: ### Setting the field validation level - {{< feature-state for_k8s_version="v1.25" state="beta" >}} + {{< feature-state for_k8s_version="v1.27" state="stable" >}} Provided that the `ServerSideFieldValidation` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled (disabled by default in 1.23 and 1.24, enabled by default starting in 1.25), you can take From 29e8e40e18351061c2a69191fedec03dd45292eb Mon Sep 17 00:00:00 2001 From: Kevin Delgado Date: Wed, 1 Feb 2023 17:29:54 +0000 Subject: [PATCH 2/2] make more timeless --- .../docs/reference/using-api/api-concepts.md | 52 ++++++++++--------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index 7bcae289be158..baff5b4104273 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -688,29 +688,13 @@ These situations are: fields via `x-kubernetes-preserve-unknown-fields`). 2. The field is duplicated in the object. -### Setting the field validation level +### Validation for unrecognized or duplicate fields (#setting-the-field-validation-level) {{< feature-state for_k8s_version="v1.27" state="stable" >}} -Provided that the `ServerSideFieldValidation` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) 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 -validation are `Ignore`, `Warn`, and `Strict`. - -{{< note >}} -If you submit a request that specifies an unrecognized field, and that is also invalid for -a different reason (for example, the request provides a string value where the API expects -an integer), then the API server responds with a 400 Bad Request error response. - -You always receive an error response in this case, no matter what field validation level you requested. -{{< /note >}} - -Field validation is set by the `fieldValidation` query parameter. The three -values that you can provide for this parameter are: +From 1.25 onward, unrecognized or duplicate fields in an object are detected via +validation on the server when you use HTTP verbs that can submit data (`POST`, `PUT`, and `PATCH`). Possible levels of +validation are `Ignore`, `Warn` (default), and `Strict`. `Ignore` : The API server succeeds in handling the request as it would without the erroneous fields @@ -730,21 +714,39 @@ 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. +The field validation level is set by the `fieldValidation` query parameter. + +{{< note >}} +If you submit a request that specifies an unrecognized field, and that is also invalid for +a different reason (for example, the request provides a string value where the API expects +an integer for a known field), then the API server responds with a 400 Bad Request error, but will +not provide any information on unknown or duplicate fields (only which fatal +error it encountered first). + +You always receive an error response in this case, no matter what field validation level you requested. +{{< /note >}} + 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. 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.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`). The default validation setting for kubectl is `--validate=true`, which means strict server-side field validation. +When kubectl cannot connect to an API server with field validation (API servers +prior to Kubernetes 1.27), it will fall back to using client-side validation. +Client-side validation will be removed entirely in a future version of kubectl. + +{{< note >}} + +Prior to Kubernetes 1.25 `kubectl --validate` was used to toggle client-side validation on or off as +a boolean flag. + +{{< /note >}} + ## Dry-run {{< feature-state for_k8s_version="v1.18" state="stable" >}}