kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Address review comments

This commit is contained in:
Jordan Liggitt 2021-02-14 15:27:04 -05:00
parent 6a6fc841d4
commit ec4df0f2cf
2 changed files with 41 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
content/en/docs/contribute/style/style-guide.md
View File

@ -576,6 +576,10 @@ Avoid making promises or giving hints about the future. If you need to talk abou
an alpha feature, put the text under a heading that identifies it as alpha an alpha feature, put the text under a heading that identifies it as alpha
information. information.
An exception to this rule is documentation about announced deprecations
targeting removal in future versions. One example of documentation like this
is the [Deprecated API migration guide](/docs/reference/using-api/deprecation-guide/).
### Avoid statements that will soon be out of date ### Avoid statements that will soon be out of date
Avoid words like "currently" and "new." A feature that is new today might not be Avoid words like "currently" and "new." A feature that is new today might not be

69
content/en/docs/reference/using-api/deprecation-guide.md
View File

@ -6,7 +6,7 @@ reviewers:
- smarterclayton - smarterclayton
title: "Deprecated API Migration Guide" title: "Deprecated API Migration Guide"
weight: 45 weight: 45
content_type: api_reference content_type: reference
--- ---
<!-- overview --> <!-- overview -->
@ -25,15 +25,23 @@ deprecated API versions to newer and more stable API versions.
The **v1.25** release will stop serving the following deprecated API versions: The **v1.25** release will stop serving the following deprecated API versions:
#### Event #### Event {#event-v125}
The **events.k8s.io/v1beta1** API version of Event will no longer be served in v1.25. The **events.k8s.io/v1beta1** API version of Event will no longer be served in v1.25.
* Migrate manifests and API clients to use the **events.k8s.io/v1** API version, available since v1.19. * Migrate manifests and API clients to use the **events.k8s.io/v1** API version, available since v1.19.
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new API
* Notable changes * Notable changes in **events.k8s.io/v1**:
* `type` is limited to `Normal` and `Warning`
* `involvedObject` is renamed to `regarding`
* `action`, `reason`, `reportingComponent`, and `reportingInstance` are required when creating new **events.k8s.io/v1** Events
* use `eventTime` instead of the deprecated `firstTimestamp` field (which is renamed to `deprecatedFirstTimestamp` and not permitted in new **events.k8s.io/v1** Events)
* use `series.lastObservedTime` instead of the deprecated `lastTimestamp` field (which is renamed to `deprecatedLastTimestamp` and not permitted in new **events.k8s.io/v1** Events)
* use `series.count` instead of the deprecated `count` field (which is renamed to `deprecatedCount` and not permitted in new **events.k8s.io/v1** Events)
* use `reportingComponent` instead of the deprecated `source.component` field (which is renamed to `deprecatedSource.component` and not permitted in new **events.k8s.io/v1** Events)
* use `reportingInstance` instead of the deprecated `source.host` field (which is renamed to `deprecatedSource.host` and not permitted in new **events.k8s.io/v1** Events)
#### RuntimeClass #### RuntimeClass {#runtimeclass-v125}
RuntimeClass in the **node.k8s.io/v1beta1** API version will no longer be served in v1.25. RuntimeClass in the **node.k8s.io/v1beta1** API version will no longer be served in v1.25.
@ -45,12 +53,12 @@ RuntimeClass in the **node.k8s.io/v1beta1** API version will no longer be served
The **v1.22** release will stop serving the following deprecated API versions: The **v1.22** release will stop serving the following deprecated API versions:
#### MutatingWebhookConfiguration and ValidatingWebhookConfiguration #### Webhook resources {#webhook-resources-v122}
The **admissionregistration.k8s.io/v1beta1** API version of MutatingWebhookConfiguration and ValidatingWebhookConfiguration will no longer be served in v1.22. The **admissionregistration.k8s.io/v1beta1** API version of MutatingWebhookConfiguration and ValidatingWebhookConfiguration will no longer be served in v1.22.
* Migrate manifests and API clients to use the **admissionregistration.k8s.io/v1** API version, available since v1.16. * Migrate manifests and API clients to use the **admissionregistration.k8s.io/v1** API version, available since v1.16.
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new APIs
* Notable changes: * Notable changes:
* `webhooks[*].failurePolicy` default changed from `Ignore` to `Fail` for v1 * `webhooks[*].failurePolicy` default changed from `Ignore` to `Fail` for v1
* `webhooks[*].matchPolicy` default changed from `Exact` to `Equivalent` for v1 * `webhooks[*].matchPolicy` default changed from `Exact` to `Equivalent` for v1
@ -59,7 +67,7 @@ The **admissionregistration.k8s.io/v1beta1** API version of MutatingWebhookConfi
* `webhooks[*].admissionReviewVersions` default value is removed and the field made required for v1 (supported versions for AdmissionReview are `v1` and `v1beta1`) * `webhooks[*].admissionReviewVersions` default value is removed and the field made required for v1 (supported versions for AdmissionReview are `v1` and `v1beta1`)
* `webhooks[*].name` must be unique in the list for objects created via `admissionregistration.k8s.io/v1` * `webhooks[*].name` must be unique in the list for objects created via `admissionregistration.k8s.io/v1`
#### CustomResourceDefinitions #### CustomResourceDefinition {#customresourcedefinition-v122}
The **apiextensions.k8s.io/v1beta1** API version of CustomResourceDefinition will no longer be served in v1.22. The **apiextensions.k8s.io/v1beta1** API version of CustomResourceDefinition will no longer be served in v1.22.
@ -73,11 +81,11 @@ The **apiextensions.k8s.io/v1beta1** API version of CustomResourceDefinition wil
* `spec.additionalPrinterColumns` is removed in v1; use `spec.versions[*].additionalPrinterColumns` instead * `spec.additionalPrinterColumns` is removed in v1; use `spec.versions[*].additionalPrinterColumns` instead
* `spec.conversion.webhookClientConfig` is moved to `spec.conversion.webhook.clientConfig` in v1 * `spec.conversion.webhookClientConfig` is moved to `spec.conversion.webhook.clientConfig` in v1
* `spec.conversion.conversionReviewVersions` is moved to `spec.conversion.webhook.conversionReviewVersions` in v1 * `spec.conversion.conversionReviewVersions` is moved to `spec.conversion.webhook.conversionReviewVersions` in v1
* `spec.versions[*].schema.openAPIV3Schema` is now required when creating v1 CustomResourceDefinitions, and must be a [structural schema](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema) * `spec.versions[*].schema.openAPIV3Schema` is now required when creating v1 CustomResourceDefinition objects, and must be a [structural schema](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema)
* `spec.preserveUnknownFields: true` is disallowed when creating v1 CustomResourceDefinitions; it must be specified within schema definitions as `x-kubernetes-preserve-unknown-fields: true` * `spec.preserveUnknownFields: true` is disallowed when creating v1 CustomResourceDefinition objects; it must be specified within schema definitions as `x-kubernetes-preserve-unknown-fields: true`
* In `additionalPrinterColumns` items, the `JSONPath` field was renamed to `jsonPath` in v1 (fixes [#66531](https://github.com/kubernetes/kubernetes/issues/66531)) * In `additionalPrinterColumns` items, the `JSONPath` field was renamed to `jsonPath` in v1 (fixes [#66531](https://github.com/kubernetes/kubernetes/issues/66531))
#### APIService #### APIService {#apiservice-v122}
The **apiregistration.k8s.io/v1beta1** API version of APIService will no longer be served in v1.22. The **apiregistration.k8s.io/v1beta1** API version of APIService will no longer be served in v1.22.
@ -85,14 +93,14 @@ The **apiregistration.k8s.io/v1beta1** API version of APIService will no longer
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new API
* No notable changes * No notable changes
#### TokenReview #### TokenReview {#tokenreview-v122}
The **authentication.k8s.io/v1beta1** API version of TokenReview will no longer be served in v1.22. The **authentication.k8s.io/v1beta1** API version of TokenReview will no longer be served in v1.22.
* Migrate manifests and API clients to use the **authentication.k8s.io/v1** API version, available since v1.6. * Migrate manifests and API clients to use the **authentication.k8s.io/v1** API version, available since v1.6.
* No notable changes * No notable changes
#### SubjectAccessReview #### SubjectAccessReview resources {#subjectaccessreview-resources-v122}
The **authorization.k8s.io/v1beta1** API version of LocalSubjectAccessReview, SelfSubjectAccessReview, and SubjectAccessReview will no longer be served in v1.22. The **authorization.k8s.io/v1beta1** API version of LocalSubjectAccessReview, SelfSubjectAccessReview, and SubjectAccessReview will no longer be served in v1.22.
@ -100,7 +108,7 @@ The **authorization.k8s.io/v1beta1** API version of LocalSubjectAccessReview, Se
* Notable changes: * Notable changes:
* `spec.group` was renamed to `spec.groups` in v1 (fixes [#32709](https://github.com/kubernetes/kubernetes/issues/32709)) * `spec.group` was renamed to `spec.groups` in v1 (fixes [#32709](https://github.com/kubernetes/kubernetes/issues/32709))
#### CertificateSigningRequest #### CertificateSigningRequest {#certificatesigningrequest-v122}
The **certificates.k8s.io/v1beta1** API version of CertificateSigningRequest will no longer be served in v1.22. The **certificates.k8s.io/v1beta1** API version of CertificateSigningRequest will no longer be served in v1.22.
@ -115,7 +123,7 @@ The **certificates.k8s.io/v1beta1** API version of CertificateSigningRequest wil
* `status.conditions[*].status` is now required * `status.conditions[*].status` is now required
* `status.certificate` must be PEM-encoded, and contain only `CERTIFICATE` blocks * `status.certificate` must be PEM-encoded, and contain only `CERTIFICATE` blocks
#### Lease #### Lease {#lease-v122}
The **coordination.k8s.io/v1beta1** API version of Lease will no longer be served in v1.22. The **coordination.k8s.io/v1beta1** API version of Lease will no longer be served in v1.22.
@ -123,7 +131,7 @@ The **coordination.k8s.io/v1beta1** API version of Lease will no longer be serve
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new API
* No notable changes * No notable changes
#### Ingress #### Ingress {#ingress-v122}
The **extensions/v1beta1** and **networking.k8s.io/v1beta1** API versions of Ingress will no longer be served in v1.22. The **extensions/v1beta1** and **networking.k8s.io/v1beta1** API versions of Ingress will no longer be served in v1.22.
@ -136,7 +144,7 @@ The **extensions/v1beta1** and **networking.k8s.io/v1beta1** API versions of Ing
* String backend `servicePort` fields are renamed to `service.port.name` * String backend `servicePort` fields are renamed to `service.port.name`
* `pathType` is now required for each specified path. Options are `Prefix`, `Exact`, and `ImplementationSpecific`. To match the undefined `v1beta1` behavior, use `ImplementationSpecific`. * `pathType` is now required for each specified path. Options are `Prefix`, `Exact`, and `ImplementationSpecific`. To match the undefined `v1beta1` behavior, use `ImplementationSpecific`.
#### IngressClass #### IngressClass {#ingressclass-v122}
The **networking.k8s.io/v1beta1** API version of IngressClass will no longer be served in v1.22. The **networking.k8s.io/v1beta1** API version of IngressClass will no longer be served in v1.22.
@ -144,15 +152,15 @@ The **networking.k8s.io/v1beta1** API version of IngressClass will no longer be
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new API
* No notable changes * No notable changes
#### RBAC #### RBAC resources {#rbac-resources-v122}
The **rbac.authorization.k8s.io/v1beta1** API version of ClusterRole, ClusterRoleBinding, Role, and RoleBinding will no longer be served in v1.22. The **rbac.authorization.k8s.io/v1beta1** API version of ClusterRole, ClusterRoleBinding, Role, and RoleBinding will no longer be served in v1.22.
* Migrate manifests and API clients to use the **networking.k8s.io/v1** API version, available since v1.8. * Migrate manifests and API clients to use the **networking.k8s.io/v1** API version, available since v1.8.
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new APIs
* No notable changes * No notable changes
#### PriorityClass #### PriorityClass {#priorityclass-v122}
The **scheduling.k8s.io/v1beta1** API version of PriorityClass will no longer be served in v1.22. The **scheduling.k8s.io/v1beta1** API version of PriorityClass will no longer be served in v1.22.
@ -160,7 +168,7 @@ The **scheduling.k8s.io/v1beta1** API version of PriorityClass will no longer be
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new API
* No notable changes * No notable changes
#### Storage #### Storage resources {#storage-resources-v122}
The **storage.k8s.io/v1beta1** API version of CSIDriver, CSINode, StorageClass, and VolumeAttachment will no longer be served in v1.22. The **storage.k8s.io/v1beta1** API version of CSIDriver, CSINode, StorageClass, and VolumeAttachment will no longer be served in v1.22.
@ -169,21 +177,21 @@ The **storage.k8s.io/v1beta1** API version of CSIDriver, CSINode, StorageClass,
* CSINode is available in **storage.k8s.io/v1** since v1.17 * CSINode is available in **storage.k8s.io/v1** since v1.17
* StorageClass is available in **storage.k8s.io/v1** since v1.6 * StorageClass is available in **storage.k8s.io/v1** since v1.6
* VolumeAttachment is available in **storage.k8s.io/v1** v1.13 * VolumeAttachment is available in **storage.k8s.io/v1** v1.13
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new APIs
* No notable changes * No notable changes
### v1.16 ### v1.16
The **v1.16** release stopped serving the following deprecated API versions: The **v1.16** release stopped serving the following deprecated API versions:
#### NetworkPolicy #### NetworkPolicy {#networkpolicy-v116}
The **extensions/v1beta1** API version of NetworkPolicy is no longer served as of v1.16. The **extensions/v1beta1** API version of NetworkPolicy is no longer served as of v1.16.
* Migrate manifests and API clients to use the **networking.k8s.io/v1** API version, available since v1.8. * Migrate manifests and API clients to use the **networking.k8s.io/v1** API version, available since v1.8.
* All existing persisted objects are accessible via the new API * All existing persisted objects are accessible via the new API
#### DaemonSet #### DaemonSet {#daemonset-v116}
The **extensions/v1beta1** and **apps/v1beta2** API versions of DaemonSet are no longer served as of v1.16. The **extensions/v1beta1** and **apps/v1beta2** API versions of DaemonSet are no longer served as of v1.16.
@ -194,7 +202,7 @@ The **extensions/v1beta1** and **apps/v1beta2** API versions of DaemonSet are no
* `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades * `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
* `spec.updateStrategy.type` now defaults to `RollingUpdate` (the default in `extensions/v1beta1` was `OnDelete`) * `spec.updateStrategy.type` now defaults to `RollingUpdate` (the default in `extensions/v1beta1` was `OnDelete`)
#### Deployment #### Deployment {#deployment-v116}
The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions of Deployment are no longer served as of v1.16. The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions of Deployment are no longer served as of v1.16.
@ -207,7 +215,7 @@ The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions
* `spec.revisionHistoryLimit` now defaults to `10` (the default in `apps/v1beta1` was `2`, the default in `extensions/v1beta1` was to retain all) * `spec.revisionHistoryLimit` now defaults to `10` (the default in `apps/v1beta1` was `2`, the default in `extensions/v1beta1` was to retain all)
* `maxSurge` and `maxUnavailable` now default to `25%` (the default in `extensions/v1beta1` was `1`) * `maxSurge` and `maxUnavailable` now default to `25%` (the default in `extensions/v1beta1` was `1`)
#### StatefulSet #### StatefulSet {#statefulset-v116}
The **apps/v1beta1** and **apps/v1beta2** API versions of StatefulSet are no longer served as of v1.16. The **apps/v1beta1** and **apps/v1beta2** API versions of StatefulSet are no longer served as of v1.16.
@ -217,7 +225,7 @@ The **apps/v1beta1** and **apps/v1beta2** API versions of StatefulSet are no lon
* `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades * `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
* `spec.updateStrategy.type` now defaults to `RollingUpdate` (the default in `apps/v1beta1` was `OnDelete`) * `spec.updateStrategy.type` now defaults to `RollingUpdate` (the default in `apps/v1beta1` was `OnDelete`)
#### ReplicaSet #### ReplicaSet {#replicaset-v116}
The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions of ReplicaSet are no longer served as of v1.16. The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions of ReplicaSet are no longer served as of v1.16.
@ -226,17 +234,14 @@ The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions
* Notable changes: * Notable changes:
* `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades * `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
## What To Do ## What to do
Kubernetes 1.22 will be released later in 2021, so be sure to audit
your configuration and integrations now!
### Test with deprecated APIs disabled ### Test with deprecated APIs disabled
You can test your clusters by starting an API server with specific API versions disabled You can test your clusters by starting an API server with specific API versions disabled
to simulate upcoming removals. Add the following flag to the API server startup arguments: to simulate upcoming removals. Add the following flag to the API server startup arguments:
`--runtime-config=$group/$version=false` `--runtime-config=<group>/<version>=false`
For example: For example:
@ -262,4 +267,4 @@ to locate use of deprecated APIs.
`kubectl-convert -f ./my-deployment.yaml --output-version apps/v1` `kubectl-convert -f ./my-deployment.yaml --output-version apps/v1`
Note that this may use non-ideal default values. To learn more about a specific Note that this may use non-ideal default values. To learn more about a specific
resource, check the Kubernetes [api reference](https://kubernetes.io/docs/reference/#api-reference). resource, check the Kubernetes [API reference](/docs/reference/kubernetes-api/).