Migrate from Helm V2 to Helm V3 - Container Service for Kubernetes

Important

Helm v2 reached end-of-life in November 2020 and no longer receives security patches or bug fixes. The helm-2to3 migration plugin has also been archived. We strongly recommend that you complete the migration to Helm v3 as soon as possible. For new clusters, install Helm v3 directly instead of following this migration procedure.

To eliminate the potential security risks imposed by the Helm v2 server Tiller, we recommend that you migrate from Helm v2 to Helm v3. Otherwise, attackers may use Tiller to install unauthorized applications in your cluster and use more Helm features without authorization. This topic describes how to migrate from Helm v2 to Helm v3.

Prerequisites

Before you begin the migration, make sure that the following conditions are met:

The Helm v2 client is installed and is currently managing releases on your cluster.
You have kubectl access to the cluster and can connect to the Kubernetes API server.
You have the necessary RBAC permissions to access the Tiller namespace and manage ConfigMaps or Secrets that store release data.
If your cluster runs Kubernetes 1.22 or later, update the API versions of your Helm-managed resources to supported versions before you migrate. For more information, see Update the API version of a Kubernetes resource using helm-mapkubeapis to perform an in-place upgrade.

Back up Helm v2 data

Before you start the migration, back up your Helm v2 data so that you can restore it if the migration fails.

Run the following command to back up the Helm v2 home directory:
```
cp -r ~/.helm ~/.helm.backup
```
Run the following command to back up the release data stored in the Tiller namespace. By default, Helm v2 stores release data as ConfigMaps in the kube-system namespace.
```
kubectl get configmaps -n kube-system -l "OWNER=TILLER" -o yaml > helm2-releases-backup.yaml
```

Migration steps

This section uses Helm v3.3.0 as an example to demonstrate how to migrate from Helm v2 to Helm v3. For more information about Helm versions, see Helm.

Note

If you can reinstall the application, you can delete the application and then reinstall it. For more information, see Helm v2 Tiller upgrade announcement.

Step 1: Install Helm v3

Run the following commands to install Helm v3:

wget https://get.helm.sh/helm-v3.3.0-linux-amd64.tar.gz
tar -xzvf helm-v3.3.0-linux-amd64.tar.gz
mv linux-amd64/helm /usr/local/bin/helm
helm version

Expected output:

version.BuildInfo{Version:"v3.3.0", GitCommit:"e29ce2a54e96cd02ccfce88bee4f58bb6e2a****", GitTreeState:"clean", GoVersion:"go1.13.4"}

Step 2: Install the Helm 2to3 plugin

Run the following commands to install the Helm 2to3 plugin. The examples in this topic use the ack-node-local-dns chart to demonstrate the migration process.

git clone https://github.com/helm/helm-2to3.git
helm plugin install ./helm-2to3

Step 3: Migrate Helm v2 configuration

Run the following commands to migrate your Helm v2 configuration, including repositories, plugins, and chart starters, to Helm v3. We recommend that you perform a dry run first to preview the changes.

Run a dry run to preview the configuration migration:
```
helm 2to3 move config --dry-run
```
If the dry-run output looks correct, run the actual migration:
```
helm 2to3 move config
```
Verify that the configuration was migrated successfully:
```
helm repo list
```

Step 4: Convert releases to Helm v3

Before you convert a release, run a dry run to verify that the conversion will succeed without making any changes:

helm 2to3 convert ack-node-local-dns --dry-run

If the dry-run output shows no errors, run the following command to convert the ack-node-local-dns chart to Helm v3:

helm 2to3 convert ack-node-local-dns --delete-v2-releases

Expected output:

2022/12/27 17:12:50 Release "ack-node-local-dns" will be converted from Helm v2 to Helm v3.
2022/12/27 17:12:50 [Helm 3] Release "ack-node-local-dns" will be created.
2022/12/27 17:12:50 [Helm 3] ReleaseVersion "ack-node-local-dns.v1" will be created.
2022/12/27 17:12:50 [Helm 3] ReleaseVersion "ack-node-local-dns.v1" created.
2022/12/27 17:12:50 [Helm 3] Release "ack-node-local-dns" created.
2022/12/27 17:12:50 [Helm 2] Release "ack-node-local-dns" will be deleted.
2022/12/27 17:12:50 [Helm 2] ReleaseVersion "ack-node-local-dns.v1" will be deleted.
2022/12/27 17:12:50 [Helm 2] ReleaseVersion "ack-node-local-dns.v1" deleted.
2022/12/27 17:12:50 [Helm 2] Release "ack-node-local-dns" deleted.
2022/12/27 17:12:50 Release "ack-node-local-dns" was converted successfully from Helm v2 to Helm v3.

After the conversion completes, verify that the release is now managed by Helm v3:

helm list -n kube-system

Repeat this step for each Helm v2 release that you want to migrate. Note that after migration, Helm v3 releases are namespace-scoped. To list releases across all namespaces, run helm list --all-namespaces.

Step 5: Clean up Helm v2 data

After you verify that all releases have been migrated successfully, clean up the remaining Helm v2 configuration and Tiller resources. This step removes Tiller from your cluster, which eliminates the security risk associated with Helm v2.

Run a dry run to preview the cleanup:
```
helm 2to3 cleanup --dry-run
```
If the dry-run output looks correct, run the actual cleanup:
```
helm 2to3 cleanup
```

Warning

After cleanup, Helm v2 will no longer be usable on this cluster. Make sure that all releases have been migrated and verified before you proceed.

FAQ

"Resource already exists" error due to inconsistent apiVersion

Problem

After you upgrade your cluster, the system prompts 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 when you migrate from Helm v2.

Cause

Clusters whose Kubernetes version is 1.22 or later no longer support v1beta1. v1beta1 is still supported in earlier Kubernetes versions. The system may return the preceding error after you upgrade your cluster.

Solution

Update the API version of the resource. For more information, see Update the API version of a Kubernetes resource using helm-mapkubeapis to perform an in-place upgrade.

Note

To avoid this error, we recommend that you update the API versions of your resources before you migrate from Helm v2 to Helm v3. See the Prerequisites section.

Error when upgrading a chart after migrating from Helm v2 to Helm v3

Problem

After you migrate from Helm v2 to v3, an error occurs when you upgrade a chart version, for example, from v1.3.5 to v1.5.3: err: 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".

Cause

The chart does not have the Helm ownership.

Solutions

You can use one of the following methods to resolve this issue:

Method 1: Assign the resource to the corresponding Helm release.

Run the following command to edit the configuration file.

kubectl edit MutatingWebhookConfiguration ack-node-local-dns-admission-controller

Add the following annotations and labels to the release.

annotations:
  meta.helm.sh/release-name: ack-node-local-dns
  meta.helm.sh/release-namespace: kube-system
labels:
  app.kubernetes.io/managed-by: Helm

Method 2: Run the following command to delete the resource.

kubectl delete MutatingWebhookConfiguration ack-node-local-dns-admission-controller