diff --git a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md b/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md index f94003e764..1227f750eb 100644 --- a/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md +++ b/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md @@ -628,11 +628,18 @@ So a webhook response to add that label would be: {{% /tab %}} {{< /tabs >}} -Starting in v1.19, admission webhooks can optionally return warning messages that are returned to the requesting client. -Warnings can be sent with allowed or rejected admission responses. -No "Warning:" prefix should be included in the message. -Warning messages should describe a problem the client making the API request should correct or be aware of. -Limit warnings to 120 characters if possible. Warnings over 256 characters and large numbers of warnings may be truncated. +Starting in v1.19, admission webhooks can optionally return warning messages that are returned to the requesting client +in HTTP `Warning` headers with a warning code of 299. Warnings can be sent with allowed or rejected admission responses. + +If you're implementing a webhook that returns a warning: +* Don't include a "Warning:" prefix in the message +* Use warning messages to describe problems the client making the API request should correct or be aware of +* Limit warnings to 120 characters if possible + +{{< caution >}} +Individual warning messages over 256 characters may be truncated by the API server before being returned to clients. +If more than 4096 characters of warning messages are added (from all sources), additional warning messages are ignored. +{{< /caution >}} {{< tabs name="AdmissionReview_response_warning" >}} {{% tab name="admission.k8s.io/v1" %}} diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/content/en/docs/reference/using-api/deprecation-policy.md index b5d6baf28d..08d55416be 100644 --- a/content/en/docs/reference/using-api/deprecation-policy.md +++ b/content/en/docs/reference/using-api/deprecation-policy.md @@ -298,17 +298,19 @@ exist and function in releases up to and including X+8. Only in release X+9, when API v1 has aged out, does the Widget resource cease to exist, and the behavior get removed. -Starting in Kubernetes 1.19, making an API request to a deprecated REST API endpoint: +Starting in Kubernetes v1.19, making an API request to a deprecated REST API endpoint: -1. returns a `Warning` header (as defined in [RFC7234, Section 5.5](https://tools.ietf.org/html/rfc7234#section-5.5)) in the API response. -2. adds a `"k8s.io/deprecated":"true"` annotation to the [audit event](/docs/tasks/debug-application-cluster/audit/) recorded for the request. -3. sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver` +1. Returns a `Warning` header (as defined in [RFC7234, Section 5.5](https://tools.ietf.org/html/rfc7234#section-5.5)) in the API response. +2. Adds a `"k8s.io/deprecated":"true"` annotation to the [audit event](/docs/tasks/debug-application-cluster/audit/) recorded for the request. +3. Sets an `apiserver_requested_deprecated_apis` gauge metric to `1` in the `kube-apiserver` process. The metric has labels for `group`, `version`, `resource`, `subresource` that can be joined to the `apiserver_request_total` metric, and a `removed_version` label that indicates the - Kubernetes release in which the API will no longer be served. The following prometheus query - would return information about requests made to deprecated APIs which will be removed in v1.22: + Kubernetes release in which the API will no longer be served. The following Prometheus query + returns information about requests made to deprecated APIs which will be removed in v1.22: - `apiserver_requested_deprecated_apis{removed_version="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total` + ```promql + apiserver_requested_deprecated_apis{removed_version="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total + ``` ### Fields of REST resources diff --git a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md index ea79f43a05..4d50a9fed9 100644 --- a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md +++ b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md @@ -276,6 +276,8 @@ the version. ### Version deprecation +{{< feature-state state="stable" for_k8s_version="v1.19" >}} + Starting in v1.19, a CustomResourceDefinition can indicate a particular version of the resource it defines is deprecated. When API requests to a deprecated version of that resource are made, a warning message is returned in the API response as a header. The warning message for each deprecated version of the resource can be customized if desired.