Merge pull request #21581 from liggitt/warning-doc

Document deprecation warnings feature

content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md

@@ -628,6 +628,54 @@ 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
+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" %}}
+```json
+{
+  "apiVersion": "admission.k8s.io/v1",
+  "kind": "AdmissionReview",
+  "response": {
+    "uid": "<value from request.uid>",
+    "allowed": true,
+    "warnings": [
+      "duplicate envvar entries specified with name MY_ENV",
+      "memory request less than 4MB specified for container mycontainer, which will not start successfully"
+    ]
+  }
+}
+```
+{{% /tab %}}
+{{% tab name="admission.k8s.io/v1beta1" %}}
+```json
+{
+  "apiVersion": "admission.k8s.io/v1beta1",
+  "kind": "AdmissionReview",
+  "response": {
+    "uid": "<value from request.uid>",
+    "allowed": true,
+    "warnings": [
+      "duplicate envvar entries specified with name MY_ENV",
+      "memory request less than 4MB specified for container mycontainer, which will not start successfully"
+    ]
+  }
+}
+```
+{{% /tab %}}
+{{< /tabs >}}
+
 ## Webhook configuration
 
 To register admission webhooks, create `MutatingWebhookConfiguration` or `ValidatingWebhookConfiguration` API objects.

content/en/docs/reference/using-api/deprecation-policy.md

@@ -298,6 +298,20 @@ 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 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` 
+   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
+   returns information about requests made to deprecated APIs which will be removed in v1.22:
+   
+   ```promql
+   apiserver_requested_deprecated_apis{removed_version="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
+   ```
+
 ### Fields of REST resources
 
 As with whole REST resources, an individual field which was present in API v1