Migrate MutatingWebhookConfiguration from admissionregistration.k8s.io/v1beta1

MutatingWebhookConfiguration registers webhooks that change objects as they are created or updated. Kubernetes 1.22 removed the v1beta1 version. In v1, sideEffects and admissionReviewVersions are required, and failurePolicy defaults to Fail, so a webhook that was optional can start blocking requests.

The error

After the upgrade to 1.22, kubectl apply fails like this:

error: resource mapping not found for name: "<name>" namespace: "<ns>" from "<file>": no matches for kind "MutatingWebhookConfiguration" in version "admissionregistration.k8s.io/v1beta1"
ensure CRDs are installed first

What replaces it

Replacement: admissionregistration.k8s.io/v1
Available since: 1.16
Deprecated in: 1.16
Removed in: 1.22

Check a manifest against 1.22, or read the official documentation.

Migration notes

webhooks[*].failurePolicy default changed from Ignore to Fail for v1
webhooks[*].matchPolicy default changed from Exact to Equivalent for v1
webhooks[*].timeoutSeconds default changed from 30s to 10s for v1
webhooks[*].sideEffects default value is removed, and the field made required, and only None and NoneOnDryRun are permitted for v1
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[*].admissionReviewVersions is required in v1. The API server sends the first version in that list that it supports, and it still supports v1beta1, so list v1 first.

Before and after

Before:

apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration
metadata:
  name: policy
webhooks:
  - name: policy.example.com
    clientConfig:
      service:
        name: policy-webhook
        namespace: policy
        path: /mutate
    rules:
      - apiGroups: ["apps"]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["deployments"]

After:

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: policy
webhooks:
  - name: policy.example.com
    clientConfig:
      service:
        name: policy-webhook
        namespace: policy
        path: /mutate
    rules:
      - apiGroups: ["apps"]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["deployments"]
    sideEffects: None
    # The webhook must accept the AdmissionReview versions listed here.
    admissionReviewVersions: ["v1"]

Helm upgrade fails after a cluster upgrade

If you installed this with Helm, helm upgrade can fail after the cluster is upgraded, even if the chart is already fixed. Which error appears depends on your Helm version and the error text:

Error: UPGRADE FAILED: unable to build kubernetes objects from current release manifest: resource mapping not found for name: "<name>" namespace: "<ns>" from "": no matches for kind "MutatingWebhookConfiguration" in version "admissionregistration.k8s.io/v1beta1"

Error: UPGRADE FAILED: current release manifest contains removed kubernetes api(s) for this kubernetes version and it is therefore unable to build the kubernetes objects for performing the diff. error from kubernetes: unable to recognize "": no matches for kind "MutatingWebhookConfiguration" in version "admissionregistration.k8s.io/v1beta1"

Helm compares your chart with the manifest stored with the release. That stored manifest still has the old API, and the cluster can no longer read it.

To check, get the stored manifest, and paste the output into the checker:

helm get manifest <release> -n <namespace>

To fix the stored record, use the helm-mapkubeapis plugin, latest tag v0.6.1. Try --dry-run first. Its README lists support for Helm v3, so check that it suits your Helm version.

helm plugin install https://github.com/helm/helm-mapkubeapis --version v0.6.1
helm mapkubeapis <release> --namespace <namespace> --dry-run

Helm's advice is to move releases to supported APIs before you upgrade the cluster, and not to roll back to a release from before that change.