Merge pull request #21581 from liggitt/warning-doc

Document deprecation warnings feature
kubernetes · Jul 15, 2020 · 78c130b · 78c130b
2 parents 38b7408 + f12bc65
commit 78c130b
Show file tree

Hide file tree

Showing 3 changed files with 145 additions and 0 deletions.
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
@@ -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.

diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/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

diff --git a/...sks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md b/...sks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md
@@ -274,6 +274,89 @@ 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
+
+{{< 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.
+
+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" >}}