Add deprecation warning info

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

@@ -628,6 +628,47 @@ 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.
+
+{{< 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,18 @@ 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:
+
+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:
+   
+   `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

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md

@@ -274,6 +274,87 @@ version sort order is `v1`, followed by `v1beta1`. This causes the kubectl
 command to use `v1` as the default version unless the provided object specifies
 the version.
 
+### Version deprecation
+
+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.
+
+A customized warning message should indicate the deprecated API group, version, and kind,
+and should indicate what API group, version, and kind should be used instead, if applicable.
+
+{{< tabs name="CustomResourceDefinition_versioning_deprecated" >}}
+{{% tab name="apiextensions.k8s.io/v1" %}}
+```yaml
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+  name: crontabs.example.com
+spec:
+  group: example.com
+  names:
+    plural: crontabs
+    singular: crontab
+    kind: CronTab
+  scope: Namespaced
+  versions:
+  - name: v1alpha1
+    served: true
+    # This indicates the v1alpha1 version of the custom resource is deprecated.
+    # API requests to this version receive a warning header in the server response.
+    deprecated: true
+    # This overrides the default warning returned to API clients making v1alpha1 API requests.
+    deprecationWarning: "example.com/v1alpha1 CronTab is deprecated; see http://example.com/v1alpha1-v1 for instructions to migrate to example.com/v1 CronTab"
+    schema: ...
+  - name: v1beta1
+    served: true
+    # This indicates the v1beta1 version of the custom resource is deprecated.
+    # API requests to this version receive a warning header in the server response.
+    # A default warning message is returned for this version.
+    deprecated: true
+    schema: ...
+  - name: v1
+    served: true
+    storage: true
+    schema: ...
+```
+{{% /tab %}}
+{{% tab name="apiextensions.k8s.io/v1beta1" %}}
+```yaml
+# Deprecated in v1.16 in favor of apiextensions.k8s.io/v1
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: crontabs.example.com
+spec:
+  group: example.com
+  names:
+    plural: crontabs
+    singular: crontab
+    kind: CronTab
+  scope: Namespaced
+  validation: ...
+  versions:
+  - name: v1alpha1
+    served: true
+    # This indicates the v1alpha1 version of the custom resource is deprecated.
+    # API requests to this version receive a warning header in the server response.
+    deprecated: true
+    # This overrides the default warning returned to API clients making v1alpha1 API requests.
+    deprecationWarning: "example.com/v1alpha1 CronTab is deprecated; see http://example.com/v1alpha1-v1 for instructions to migrate to example.com/v1 CronTab"
+  - name: v1beta1
+    served: true
+    # This indicates the v1beta1 version of the custom resource is deprecated.
+    # API requests to this version receive a warning header in the server response.
+    # A default warning message is returned for this version.
+    deprecated: true
+  - name: v1
+    served: true
+    storage: true
+```
+{{% /tab %}}
+{{< /tabs >}}
+
+
 ## Webhook conversion
 
 {{< feature-state state="stable" for_k8s_version="v1.16" >}}