Merge pull request #21581 from liggitt/warning-doc
Document deprecation warnings feature
This commit is contained in:
Kubernetes Prow Robot
GitHub
commit
78c130b286
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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" >}}
|
||||
|
|
|
|||
Loading…
Reference in New Issue