Merge pull request #28694 from sftim/20210629_announce_kubernetes_1.21_api_removals
Add article about upcoming Kubernetes API removals
This commit is contained in:
Kubernetes Prow Robot
@@ -0,0 +1,264 @@
|
||||
---
|
||||
layout: blog
|
||||
title: "Kubernetes API and Feature Removals In 1.22: Here’s What You Need To Know"
|
||||
date: 2021-07-14
|
||||
slug: upcoming-changes-in-kubernetes-1-22
|
||||
---
|
||||
|
||||
**Authors**: Krishna Kilari (Amazon Web Services), Tim Bannister (The Scale Factory)
|
||||
|
||||
As the Kubernetes API evolves, APIs are periodically reorganized or upgraded.
|
||||
When APIs evolve, the old APIs they replace are deprecated, and eventually removed.
|
||||
See [Kubernetes API removals](#kubernetes-api-removals) to read more about Kubernetes'
|
||||
policy on removing APIs.
|
||||
|
||||
We want to make sure you're aware of some upcoming removals. These are
|
||||
beta APIs that you can use in current, supported Kubernetes versions,
|
||||
and they are already deprecated. The reason for all of these removals
|
||||
is that they have been superseded by a newer, stable (“GA”) API.
|
||||
|
||||
Kubernetes 1.22, due for release in August 2021, will remove a number of deprecated
|
||||
APIs.
|
||||
[Kubernetes 1.22 Release Information](https://www.kubernetes.dev/resources/release/)
|
||||
has details on the schedule for the v1.22 release.
|
||||
|
||||
## API removals for Kubernetes v1.22 {#api-changes}
|
||||
|
||||
The **v1.22** release will stop serving the API versions we've listed immediately below.
|
||||
These are all beta APIs that were previously deprecated in favor of newer and more stable
|
||||
API versions.
|
||||
<!-- sorted by API group -->
|
||||
|
||||
* Beta versions of the `ValidatingWebhookConfiguration` and `MutatingWebhookConfiguration` API (the **admissionregistration.k8s.io/v1beta1** API versions)
|
||||
* The beta `CustomResourceDefinition` API (**apiextensions.k8s.io/v1beta1**)
|
||||
* The beta `APIService` API (**apiregistration.k8s.io/v1beta1**)
|
||||
* The beta `TokenReview` API (**authentication.k8s.io/v1beta1**)
|
||||
* Beta API versions of `SubjectAccessReview`, `LocalSubjectAccessReview`, `SelfSubjectAccessReview` (API versions from **authorization.k8s.io/v1beta1**)
|
||||
* The beta `CertificateSigningRequest` API (**certificates.k8s.io/v1beta1**)
|
||||
* The beta `Lease` API (**coordination.k8s.io/v1beta1**)
|
||||
* All beta `Ingress` APIs (the **extensions/v1beta1** and **networking.k8s.io/v1beta1** API versions)
|
||||
|
||||
|
||||
## What to do
|
||||
|
||||
We're going to run through each of the resources that are affected by these removals
|
||||
and explain the steps you'll need to take.
|
||||
|
||||
`Ingress`
|
||||
: Migrate to use the **networking.k8s.io/v1**
|
||||
[Ingress](/docs/reference/kubernetes-api/service-resources/ingress-v1/) API,
|
||||
[available since v1.19](/blog/2020/08/26/kubernetes-release-1.19-accentuate-the-paw-sitive/#ingress-graduates-to-general-availability).
|
||||
The related API [IngressClass](/docs/reference/kubernetes-api/service-resources/ingress-class-v1/)
|
||||
is designed to complement the [Ingress](/docs/concepts/services-networking/ingress/)
|
||||
concept, allowing you to configure multiple kinds of Ingress within one cluster.
|
||||
If you're currently using the deprecated
|
||||
[`kubernetes.io/ingress.class`](https://kubernetes.io/docs/reference/labels-annotations-taints/#kubernetes-io-ingress-class-deprecated)
|
||||
annotation, plan to switch to using the `.spec.ingressClassName` field instead.
|
||||
On any cluster running Kubernetes v1.19 or later, you can use the v1 API to
|
||||
retrieve or update existing Ingress objects, even if they were created using an
|
||||
older API version.
|
||||
|
||||
When you convert an Ingress to the v1 API, you should review each rule in that Ingress.
|
||||
Older Ingresses use the legacy `ImplementationSpecific` path type. Instead of `ImplementationSpecific`, switch [path matching](/docs/concepts/services-networking/ingress/#path-types) to either `Prefix` or `Exact`. One of the benefits of moving to these alternative path types is that it becomes easier to migrate between different Ingress classes.
|
||||
|
||||
**ⓘ** As well as upgrading _your_ own use of the Ingress API as a client, make sure that
|
||||
every ingress controller that you use is compatible with the v1 Ingress API.
|
||||
Read [Ingress Prerequisites](/docs/concepts/services-networking/ingress/#prerequisites)
|
||||
for more context about Ingress and ingress controllers.
|
||||
|
||||
`ValidatingWebhookConfiguration` and `MutatingWebhookConfiguration`
|
||||
: Migrate to use the **admissionregistration.k8s.io/v1** API versions of
|
||||
[ValidatingWebhookConfiguration](/docs/reference/kubernetes-api/extend-resources/validating-webhook-configuration-v1/)
|
||||
and [MutatingWebhookConfiguration](/docs/reference/kubernetes-api/extend-resources/mutating-webhook-configuration-v1/),
|
||||
available since v1.16.
|
||||
You can use the v1 API to retrieve or update existing objects, even if they were created using an older API version.
|
||||
|
||||
`CustomResourceDefinition`
|
||||
: Migrate to use the [CustomResourceDefinition](/docs/reference/kubernetes-api/extend-resources/custom-resource-definition-v1/)
|
||||
**apiextensions.k8s.io/v1** API, available since v1.16.
|
||||
You can use the v1 API to retrieve or update existing objects, even if they were created
|
||||
using an older API version. If you defined any custom resources in your cluster, those
|
||||
are still served after you upgrade.
|
||||
|
||||
If you're using external CustomResourceDefinitions, you can use
|
||||
[`kubectl convert`](#kubectl-convert) to translate existing manifests to use the newer API.
|
||||
Because there are some functional differences between beta and stable CustomResourceDefinitions,
|
||||
our advice is to test out each one to make sure it works how you expect after the upgrade.
|
||||
|
||||
`APIService`
|
||||
: Migrate to use the **apiregistration.k8s.io/v1** [APIService](/docs/reference/kubernetes-api/cluster-resources/api-service-v1/)
|
||||
API, available since v1.10.
|
||||
You can use the v1 API to retrieve or update existing objects, even if they were created using an older API version.
|
||||
If you already have API aggregation using an APIService object, this aggregation continues
|
||||
to work after you upgrade.
|
||||
|
||||
`TokenReview`
|
||||
: Migrate to use the **authentication.k8s.io/v1** [TokenReview](/docs/reference/kubernetes-api/authentication-resources/token-review-v1/)
|
||||
API, available since v1.10.
|
||||
|
||||
In Kubernetes version v1.21 and earlier, the Kubernetes API server
|
||||
[defaults](/docs/reference/access-authn-authz/authentication/#webhook-token-authentication)
|
||||
to sending _beta_ TokenReviews to webhooks. See [Rehearse for the upgrade](#rehearse-for-the-upgrade)
|
||||
for some specific tips about switching to the stable API.
|
||||
|
||||
`SubjectAccessReview`, `SelfSubjectAccessReview` and `LocalSubjectAccessReview`
|
||||
: Migrate to use the **authorization.k8s.io/v1** versions of those
|
||||
[authorization APIs](/docs/reference/kubernetes-api/authorization-resources/), available since v1.6.
|
||||
|
||||
`CertificateSigningRequest`
|
||||
: Migrate to use the **certificates.k8s.io/v1**
|
||||
[CertificateSigningRequest](/docs/reference/kubernetes-api/authentication-resources/certificate-signing-request-v1/)
|
||||
API, available since v1.19.
|
||||
You can use the v1 API to retrieve or update existing objects, even if they were created
|
||||
using an older API version. Existing issued certificates retain their validity when you upgrade.
|
||||
|
||||
`Lease`
|
||||
: Migrate to use the **coordination.k8s.io/v1** [Lease](/docs/reference/kubernetes-api/cluster-resources/lease-v1/)
|
||||
API, available since v1.14.
|
||||
You can use the v1 API to retrieve or update existing objects, even if they were created
|
||||
using an older API version.
|
||||
|
||||
### `kubectl convert`
|
||||
|
||||
There is a plugin to `kubectl` that provides the `kubectl convert` subcommand.
|
||||
It's an official plugin that you can download as part of Kubernetes.
|
||||
See [Download Kubernetes](/releases/download/) for more details.
|
||||
|
||||
You can use `kubectl convert` to update manifest files to use a different API
|
||||
version. For example, if you have a manifest in source control that uses the beta
|
||||
Ingress API, you can check that definition out,
|
||||
and run
|
||||
`kubectl convert -f <manifest> --output-version <group>/<version>`.
|
||||
You can use the `kubectl convert` command to automatically convert an
|
||||
existing manifest.
|
||||
|
||||
For example, to convert an older Ingress definition to
|
||||
`networking.k8s.io/v1`, you can run:
|
||||
```bash
|
||||
kubectl convert -f ./legacy-ingress.yaml --output-version networking.k8s.io/v1
|
||||
```
|
||||
|
||||
The automatic conversion uses a similar technique to how the Kubernetes control plane
|
||||
updates objects that were originally created using an older API version. Because it's
|
||||
a mechanical conversion, you might need to go in and change the manifest to adjust
|
||||
defaults etc.
|
||||
|
||||
### Rehearse for the upgrade
|
||||
|
||||
If you manage your cluster's API server component, you can try out these API
|
||||
removals before you upgrade to Kubernetes v1.22.
|
||||
|
||||
To do that, add the following to the kube-apiserver command line arguments:
|
||||
|
||||
`--runtime-config=admissionregistration.k8s.io/v1beta1=false,apiextensions.k8s.io/v1beta1=false,apiregistration.k8s.io/v1beta1=false,authentication.k8s.io/v1beta1=false,authorization.k9s.io/v1=false,certificates.k8s.io/v1beta=false,coordination.k8s.io/v1beta1=false,extensions/v1beta1/ingresses=false,networking.k8s.io/v1beta1/ingresses=false,networking.k8s.io/v1beta1/ingressclasses=false`
|
||||
|
||||
Once you've switched all the kube-apiservers in your cluster to use that setting,
|
||||
those beta APIs are removed. You can test that API clients (`kubectl`, deployment
|
||||
tools, custom controllers etc) still work how you expect, and you can revert if
|
||||
you need to without having to plan a more disruptive downgrade.
|
||||
|
||||
|
||||
There's another setting that's relevant if you use webhook authentication checks.
|
||||
Kubernetes v1.22 is the first version of Kubernetes that sends TokenReview objects
|
||||
to webhooks using the `authentication.k8s.io/v1` API by default. However, you can
|
||||
switch over earlier to try it out.
|
||||
Add `--authentication-token-webhook-version=v1` to the command line options for
|
||||
the kube-apiserver, and check that webhooks for authentication still work how you
|
||||
expected.
|
||||
|
||||
Once you're happy it works, you can leave the `--authentication-token-webhook-version=v1`
|
||||
option set through and after the upgrade to v1.22.
|
||||
|
||||
### Advice for software authors
|
||||
|
||||
Maybe you're reading this because you're a developer of an addon or other
|
||||
component that integrates with Kubernetes?
|
||||
|
||||
If you develop an Ingress controller, webhook authenticator, an API aggregation, or
|
||||
any other tool that relies on these deprecated APIs, you should already have started
|
||||
to switch your software over.
|
||||
|
||||
You can use the tips in
|
||||
[Rehearse for the upgrade](#rehearse-for-the-upgrade) to run your own Kubernetes
|
||||
cluster that only uses the new APIs, and make sure that your code works OK.
|
||||
For your documentation, make sure readers are aware of any steps they should take
|
||||
for the Kubernetes v1.22 upgrade.
|
||||
|
||||
Where possible, give your users a hand to adopt the new APIs early - perhaps in a
|
||||
test environment - so they can give you feedback about any problems.
|
||||
|
||||
There are some [more deprecations](#looking-ahead) coming in Kubernetes v1.25,
|
||||
so plan to have those covered too.
|
||||
|
||||
## Kubernetes API removals
|
||||
|
||||
Here's some background about why Kubernetes removes some APIs, and also a promise
|
||||
about _stable_ APIs in Kubernetes.
|
||||
|
||||
Kubernetes follows a defined
|
||||
[deprecation policy](/docs/reference/using-api/deprecation-policy/) for its
|
||||
features, including the Kubernetes API. That policy allows for replacing stable
|
||||
(“GA”) APIs from Kubernetes. Importantly, this policy means that a stable API only
|
||||
be deprecated when a newer stable version of that same API is available.
|
||||
|
||||
That stability guarantee matters: if you're using a stable Kubernetes API, there
|
||||
won't ever be a new version released that forces you to switch to an alpha or beta
|
||||
feature.
|
||||
|
||||
Earlier stages are different. Alpha features are under test and potentially
|
||||
incomplete. Almost always, alpha features are disabled by default.
|
||||
Kubernetes releases can and do remove alpha features that haven't worked out.
|
||||
|
||||
After alpha, comes beta. These features are typically enabled by default; if the
|
||||
testing works out, the feature can graduate to stable. If not, it might need
|
||||
a redesign.
|
||||
|
||||
Last year, Kubernetes officially
|
||||
[adopted](/blog/2020/08/21/moving-forward-from-beta/#avoiding-permanent-beta)
|
||||
a policy for APIs that have reached their beta phase:
|
||||
|
||||
> For Kubernetes REST APIs, when a new feature's API reaches beta, that starts
|
||||
> a countdown. The beta-quality API now has three releases …
|
||||
> to either:
|
||||
>
|
||||
> * reach GA, and deprecate the beta, or
|
||||
> * have a new beta version (and deprecate the previous beta).
|
||||
|
||||
_At the time of that article, three Kubernetes releases equated to roughly nine
|
||||
calendar months. Later that same month, Kubernetes
|
||||
adopted a new
|
||||
release cadence of three releases per calendar year, so the countdown period is
|
||||
now roughly twelve calendar months._
|
||||
|
||||
Whether an API removal is because of a beta feature graduating to stable, or
|
||||
because that API hasn't proved successful, Kubernetes will continue to remove
|
||||
APIs by following its deprecation policy and making sure that migration options
|
||||
are documented.
|
||||
|
||||
### Looking ahead
|
||||
|
||||
The upcoming **v1.25** release will stop serving beta versions of several Kubernetes APIs
|
||||
that have been stable for some time. The same release **removes** PodSecurityPolicy,
|
||||
which is deprecated and won't graduate to stable. See
|
||||
[PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/)
|
||||
for more information.
|
||||
|
||||
The official [list of API removals](/docs/reference/using-api/deprecation-guide/#v1-25)
|
||||
planned for Kubernetes 1.25 is:
|
||||
|
||||
* The beta `CronJob` API (**batch/v1beta1**)
|
||||
* The beta `EndpointSlice` API (**networking.k8s.io/v1beta1**)
|
||||
* The beta `PodDisruptionBudget` API (**policy/v1beta1**)
|
||||
* The beta `PodSecurityPolicy` API (**policy/v1beta1**)
|
||||
|
||||
## Want to know more?
|
||||
|
||||
Deprecations are announced in the Kubernetes release notes. You can see the announcements
|
||||
of pending deprecations in the release notes for
|
||||
[1.19](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.19.md#deprecations),
|
||||
[1.20](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.20.md#deprecation),
|
||||
and [1.21](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.21.md#deprecation).
|
||||
|
||||
For information on the process of deprecation and removal, check out the official Kubernetes
|
||||
[deprecation policy](/docs/reference/using-api/deprecation-policy/#deprecating-parts-of-the-api)
|
||||
document.
|
||||
Reference in New Issue
Block a user