Home

Awesome

This project is no longer supported.

Helm 2to3 Plugin

License Go Report Card CircleCI Release

diagram

Helm v3 plugin which migrates and cleans up Helm v2 configuration and releases in-place to Helm v3

⚠️ Deprecation and Archive Notice

The 2to3 plugin is deprecated and no longer supported. Helm 3 was released in November 2019 and Helm 2 became unsupported in November 2020. It would be expected that all users should be migrated to Helm 3 by this time. Therefore, the plugin has now been deprecated by the maintainers.

Overview

One of the most important aspects of upgrading to a new major release of Helm is the migration of data. This is especially true of Helm v2 to v3 considering the architectural changes between the releases. The 2to3 plugin helps with this migration by supporting:

Readme before migration

WARNING: All data migrations carry a level of risk. Helm v2 migration is no different. You should be aware of any risks specific to your environment and prepare a data migration strategy for your needs.

Here are some suggestions to mitigate against potential risks during migration:

Note: A Helm v2 client:

This means that you have to cognisant of this when migrating as releases are deployed into clusters by Tiller and its namespace. You have to therefore be aware of migrating for each cluster and each Tiller instance that is managed by the Helm v2 client instance. Clean up should only be run once all migration for a Helm v2 client is complete.

Prerequisite

Recommended Prior to Migration

This is a list of recommendations prior to migration:

Install

Based on the version in plugin.yaml, release binary will be downloaded from GitHub:

$ helm plugin install https://github.com/helm/helm-2to3.git
Downloading and installing helm-2to3 v0.1.3 ...
https://github.com/helm/helm-2to3/releases/download/v0.1.3/helm-2to3_0.1.3_darwin_amd64.tar.gz
Installed plugin: 2to3

For Windows (using WSL)

Helm's plugin install hook system relies on /bin/sh, regardless of the operating system present. Windows users can work around this by using Helm under WSL.

$ wget https://get.helm.sh/helm-v3.0.0-linux-amd64.tar.gz
$ tar xzf helm-v3.0.0-linux-amd64.tar.gz
$ ./linux-amd64/helm plugin install https://github.com/helm/helm-2to3

Usage

Migrate Helm v2 configuration

Migrate Helm v2 configuration in-place to Helm v3:

$ helm 2to3 move config [flags]

Flags:

      --dry-run  simulate a command
      --skip-confirmation   if set, skips confirmation message before performing move
  -h, --help     help for move

It will migrate:

Note:

$ export HELM_V2_HOME=$PWD/.helm2
$ export HELM_V3_CONFIG=$PWD/.helm3
$ export HELM_V3_DATA=$PWD/.helm3
$ helm 2to3 move config

Readme after configuration migration

Migrate Helm v2 releases

Migrate Helm v2 releases in-place to Helm v3

$ helm 2to3 convert [flags] RELEASE

Flags:

      --delete-v2-releases         v2 release versions are deleted after migration. By default, the v2 release versions are retained
      --dry-run                    simulate a command
  -h, --help                       help for convert
      --ignore-already-migrated    Ignore any already migrated release versions and continue migrating
      --kube-context string        name of the kubeconfig context to use
      --kubeconfig string          path to the kubeconfig file
  -l, --label string               label to select Tiller resources by (default "OWNER=TILLER")
  -s, --release-storage string     v2 release storage type/object. It can be 'secrets' or 'configmaps'. This is only used with the 'tiller-out-cluster' flag (default "secrets")
      --release-versions-max int   limit the maximum number of versions converted per release. Use 0 for no limit (default 10)
  -t, --tiller-ns string           namespace of Tiller (default "kube-system")
      --tiller-out-cluster         when  Tiller is not running in the cluster e.g. Tillerless

Note: There is a limit set on the number of versions/revisions of a release that are converted. It is defaulted to 10 but can be configured with the --release-versions-max flag. When the limit set is less that the actual number of versions then only the latest release versions up to the limit will be converted. Older release versions with not be converted. If --delete-v2-releases is set, these older versions will remain in Helm v2 storage but will no longer be visible to Helm v2 commands like helm list. Clean up will remove them from storage.

Clean up Helm v2 data

Clean up Helm v2 configuration, release data and Tiller deployment:

$ helm 2to3 cleanup [flags]

Flags:

      --config-cleanup           if set, configuration cleanup performed
      --dry-run                  simulate a command
  -h, --help                     help for cleanup
      --kube-context string      name of the kubeconfig context to use
      --kubeconfig string        path to the kubeconfig file
  -l, --label string             label to select Tiller resources by (default "OWNER=TILLER")
      --name string              the release name. When it is specified, the named release and its versions will be removed only. Should not be used with other cleanup operations
      --release-cleanup          if set, release data cleanup performed
  -s, --release-storage string   v2 release storage type/object. It can be 'secrets' or 'configmaps'. This is only used with the 'tiller-out-cluster' flag (default "secrets")
      --skip-confirmation        if set, skips confirmation message before performing cleanup
      --tiller-cleanup           if set, Tiller cleanup performed
  -t, --tiller-ns string         namespace of Tiller (default "kube-system")
      --tiller-out-cluster       when  Tiller is not running in the cluster e.g. Tillerless

A full clean will remove the:

Note: Before performing a full or release data clean, remove any Helm v2 releases which have not been migrated to Helm v3 and are unwanted. They can be removed using the Helm v2 delete command. If they are not removed before clean up of the v2 release data then the Kubernetes resources deployed by the Helm release will remain in your cluster. In other words, the resources will be 'orphaned' without any Helm release associated.

Cleanup of individual parts can be performed using the following flags:

If none of these flags are set, then full cleanup is performed.

The cleanup uses the default Helm v2 home folder. To override this folder you need to set the environment variable HELM_V2_HOME:

$ export HELM_V2_HOME=$PWD/.helm2
$ helm 2to3 cleanup

Warning: The full cleanup command will remove the Helm v2 Configuration, Release Data and Tiller Deployment. It cleans up all releases managed by Helm v2. It will not be possible to restore them if you haven't made a backup of the releases. Helm v2 will not be usable afterwards. Full cleanup should only be run once all migration (clusters and Tiller instances) for a Helm v2 client instance is complete. Helm v2 may also become unusable depending on cleanup of individual parts.

Troubleshooting

Q. I get an error when I try to do a chart dependency update in Helm v3 after configuration migration

Error might be similar to the following:

$ helm dep update chrt-1/
Hang tight while we grab the latest from your chart repositories...
...Unable to get an update from the "local" chart repository (http://127.0.0.1:8879/charts):
Get http://127.0.0.1:8879/charts/index.yaml: dial tcp 127.0.0.1:8879: connect: connection refused
...Successfully got an update from the "stable" chart repository
Update Complete. ⎈Happy Helming!⎈
Error: open /home/usr1/.cache/helm/repository/local-index.yaml: no such file or directory

A. Local respoitories are not copied to Helm v3. You therefore need to remove all local repositories from Helm v3 using <helm3> repo remove and re-add where required using <helm3> repo add. This is a necessary refresh to align references for Helm v3 and remove the conflict. It is worthwhile to also refresh the repository list afterwards: <helm3> repo update. You should then be able to run the chart dependency update command successfully.

Q. I get an error when I try to do a helm upgrade in Helm v3 after migration

Error might be similar to the following:

$ helm upgrade nginx bitnami/nginx
Error: failed to download "bitnami/nginx" (hint: running `helm repo update` may help)

A. This can happen when there are conflicts in the local repository list that Helm v3 cannot resolve. This can be fixed by running the helm repo update command.

Frequently Asked Questions

Q. How do you perform Helm v2 release migration as a batch operation?

A. You can perform batch migration of releases using a command as follows:

$ kubectl get [configmap|secret] -n <tiller_namespace> \
 -l "OWNER=TILLER" | awk '{print $1}' | grep -v NAME | cut -d '.' -f1 | uniq | xargs -n1 helm 2to3 convert

An example of migrating releases which are stored as ConfigMaps in Tiller namespace kube-system:

$ kubectl get configmap -n kube-system -l "OWNER=TILLER" \
 | awk '{print $1}' | grep -v NAME | cut -d '.' -f1 | uniq | xargs -n1 helm 2to3 convert

Developer (From Source) Install

If you would like to handle the build yourself, this is the recommended way to do it.

You must first have Go v1.22 installed, and then you run:

$ git clone git@github.com:helm/helm-2to3.git
$ cd helm-2to3
$ make build
$ export HELM_LINTER_PLUGIN_NO_INSTALL_HOOK=true
$ helm plugin install <your_path>/helm-2to3

That last command will use the binary that you built.