Update the API version of a Kubernetes resource by using helm-mapkubeapis - Container Service for Kubernetes

You can use helm-mapkubeapis to update the deprecated or removed Kubernetes APIs in the metadata of a Helm release to supported Kubernetes APIs. It helps reduce workloads and risks to ensure the stability of your service. This topic describes how to update the API version of a Kubernetes resource by using helm-mapkubeapis to perform an in-place upgrade.

Scenarios

In Kubernetes 1.22 and later, multiple new API versions are released for Kubernetes resource objects. When you update Helm charts, the following error messages may be returned: To fix the preceding errors, you can update the API versions of the Kubernetes resources.

rendered manifests contain a new resource that already exists. Unable to continue with update: existing resource conflict: kind: MutatingWebhookConfiguration, namespace: , name: mse-pilot-ack-mse-pilot

Error: UPGRADE FAILED: rendered manifests contain a resource that already exists. Unable to continue with update: MutatingWebhookConfiguration "ack-node-local-dns-admission-controller" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "ack-node-local-dns"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "kube-system"

Prerequisites

Go 1.13 or later is installed. For more information, see Go 1.13.

Step 1: Download and install helm-mapkubeapis

Run the following command to download and install helm-mapkubeapis:

mkdir -p ${GOPATH}/src/github.com
cd $_
git clone git@github.com:helm/helm-mapkubeapis.git
cd helm-mapkubeapis
make
export HELM_LINTER_PLUGIN_NO_INSTALL_HOOK=true
helm plugin install <your_path>/helm-mapkubeapis

Step 2: Update the API version

This example describes how to update the API version of the MutatingWebhookConfiguration resource for the ack-node-local-dns release.

Run the following command to view the history of the API version of the MutatingWebhookConfiguration resource:

vim  ${GOPATH}/src/github.com/helm-mapkubeapis/config/Map.yaml

Expected output:

  - deprecatedAPI: "apiVersion: admissionregistration.k8s.io/v1beta1\nkind: MutatingWebhookConfiguration"
    newAPI: "apiVersion: admissionregistration.k8s.io/v1\nkind: MutatingWebhookConfiguration"
    deprecatedInVersion: "v1.17"
    removedInVersion: "v1.20"

The output shows that the API version of the MutatingWebhookConfiguration resource will be updated from v1beta1 to v1 in Kubernetes 1.20 and later.

Run the following command to check whether the API version in the ack-node-local-dns release needs to be updated:

helm mapkubeapis ack-node-local-dns --namespace kube-system --dry-run

Expected output:

2022/01/18 14:21:57 NOTE: This is in dry-run mode, the following actions will not be executed.
2022/01/18 14:21:57 Run without --dry-run to take the actions described below:
2022/01/18 14:21:57
2022/01/18 14:21:57 Release 'ack-node-local-dns' will be checked for deprecated or removed Kubernetes APIs and will be updated if necessary to supported API versions.
2022/01/18 14:21:57 Get release 'ack-node-local-dns' latest version.
2022/01/18 14:21:57 Check release 'ack-node-local-dns' for deprecated or removed APIs...
2022/01/18 14:21:57 Found deprecated or removed Kubernetes API:
"apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration"
Supported API equivalent:
"apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration"
2022/01/18 14:21:57 Finished checking release 'ack-node-local-dns' for deprecated or removed APIs.
2022/01/18 14:21:57 Deprecated or removed APIs exist, updating release: ack-node-local-dns.
2022/01/18 14:21:57 Map of release 'ack-node-local-dns' deprecated or removed APIs to supported versions, completed successfully.

Found deprecated or removed Kubernetes API is returned in the output. This indicates that API version needs to be updated.

Run the following command to update the API version of the MutatingWebhookConfiguration resource from v1beta1 to v1.

helm mapkubeapis ack-node-local-dns --namespace kube-system

Expected output:

2022/01/18 14:31:38 Release 'ack-node-local-dns' will be checked for deprecated or removed Kubernetes APIs and will be updated if necessary to supported API versions.
2022/01/18 14:31:38 Get release 'ack-node-local-dns' latest version.
2022/01/18 14:31:38 Check release 'ack-node-local-dns' for deprecated or removed APIs...
2022/01/18 14:31:38 Found deprecated or removed Kubernetes API:
"apiVersion: admissionregistration.k8s.io/v1beta1
kind: MutatingWebhookConfiguration"
Supported API equivalent:
"apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration"
2022/01/18 14:31:38 Finished checking release 'ack-node-local-dns' for deprecated or removed APIs.
2022/01/18 14:31:38 Deprecated or removed APIs exist, updating release: ack-node-local-dns.
2022/01/18 14:31:38 Set status of release version 'ack-node-local-dns.v9' to 'superseded'.
2022/01/18 14:31:38 Release version 'ack-node-local-dns.v9' updated successfully.
2022/01/18 14:31:38 Add release version 'ack-node-local-dns.v10' with updated supported APIs.
2022/01/18 14:31:38 Release version 'ack-node-local-dns.v10' added successfully.
2022/01/18 14:31:38 Release 'ack-node-local-dns' with deprecated or removed APIs updated successfully to new version.
2022/01/18 14:31:38 Map of release 'ack-node-local-dns' deprecated or removed APIs to supported versions, completed successfully.

Release 'ack-node-local-dns' with deprecated or removed APIs updated successfully to new version. is returned in the output. This indicates that the API version of the MutatingWebhookConfiguration resource is updated from v1beta1 to v1.