Add article about upcoming Kubernetes API removals

Co-Authored-By: Sivakrishna Kilari <[email protected]>
Co-authored-by: Sandro Cirulli <[email protected]>

Author: 3 people

content/en/blog/_posts/2021-07-14-upcoming-changes-in-kubernetes-1-22/index.md

@@ -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 &hellip;
+> 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.