This repository contains the instructions and code necessary to do the Oct. 2020 Helm workshop hosted by CNCF.
You should have a Kubernetes cluster running, and have basically all the privileges. Do NOT use your production cluster, because we are gonna do some high-risk things. I recommend Docker Desktop (in Kubernetes mode), Kind, Minikube, or k3s running locally.
You should also get a copy of Helm 2. Later you will be replacing this with Helm 3. For my
demos, I have helm2 aliased to Helm 2, and helm3 aliased to Helm 3.
If you are just getting Helm 2 setup, you may need to do something like this:
$ kubectl apply -f https://raw.githubusercontent.com/technosophos/helm-2to3-migration-workshop/master/tiller-rbac.yaml
$ helm2 init --service-account tiller
In the course of doing the workshop below, you may find you need some additional references or documentation. Here are some good sources:
- Official blog post on migrating
- Helm 3 documentation
- Helm 2 documentation
- ArtifactHub package search
- Official deprecation timeline
- The Helm 2to3 Plugin
- Configuring Helm to use the NEW charts repository
We are going to start with Helm 2, install some things, and then perform a migration.
We'll be using a few charts from Bitnami's repository.
$ helm2 repo add bitnami https://charts.bitnami.com/bitnamiNext we can install a few charts. We'll do wordpress and drupal because they are each
reasonably complex. We'll also set a few values just to verify that the migration works.
$ helm2 install bitnami/drupal --set drupalEmail=me@example.com -n drupal
$ helm2 install bitnami/wordpress --set wordpressEmail=me@example.com -n wordpressYou can verify that these are installed:
$ helm2 ls
NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE
drupal 1 Tue Oct 20 14:08:21 2020 DEPLOYED drupal-9.1.0 9.0.7 drupal
wordpress 1 Tue Oct 20 14:09:50 2020 DEPLOYED wordpress-9.8.0 5.5.1 wordpress At this point, we have a few things to migrate.
You will need Helm 3 to continue this workshop.
Check out the installation guide for instructions on how to get it.
I have installed mine manually, and aliased the helm3 command to it (alias helm3=/Users/technosophos/Code/Go/src/helm.sh/helm/bin/helm).
You don't have to do this but you need to distinguish between Helm 2 and 3 as binaries are both named helm.
You can double-check that your helm version is 3 using the helm version command:
$ helm3 version
version.BuildInfo{Version:"v3.3+unreleased", GitCommit:"caa68e78decd8cdb4e3e6368988f13ec08884070", GitTreeState:"clean", GoVersion:"go1.15.2"}Next, we will install a Helm 3 plugin that allows us to do Helm 2-to-3 migrations:
$ helm3 plugin install https://github.com/helm/helm-2to3
Downloading and installing helm-2to3 v0.7.0 ...
https://github.com/helm/helm-2to3/releases/download/v0.7.0/helm-2to3_0.7.0_darwin_amd64.tar.gz
Installed plugin: 2to3We can verify that the plugin was installed:
$ helm3 plugin list
NAME VERSION DESCRIPTION
2to3 0.7.0 migrate and cleanup Helm v2 configuration and releases in-place to Helm v3We can read the plugin documentation with the --help flag:
$ helm3 2to3 --help
Migrate and Cleanup Helm v2 configuration and releases in-place to Helm v3
Usage:
2to3 [command]
Available Commands:
cleanup cleanup Helm v2 configuration, release data and Tiller deployment
convert migrate Helm v2 release in-place to Helm v3
help Help about any command
move migrate Helm v2 configuration in-place to Helm v3
Flags:
-h, --help help for 2to3
Use "2to3 [command] --help" for more information about a command.Now we're ready to do the actual migration.
If you have just installed Helm 3, you will have no configured repositories, plugins, or starters. But you may have had some of those things configured in your Helm 2 instance.
Check what's in your Helm 2 instance:
$ helm2 repo list
$ helm2 plugin listAnd check what's in your Helm 3 instance:
$ helm3 repo list
$ helm3 plugin listFor example, earlier we configured Helm 2 to use the Bitnami charts repository.
We can use the helm3 2to3 move command to migrate our configuration.
First, we'll do it in --dry-run mode:
$ helm3 2to3 move config --dry-run
2020/10/20 14:25:52 NOTE: This is in dry-run mode, the following actions will not be executed.
2020/10/20 14:25:52 Run without --dry-run to take the actions described below:
2020/10/20 14:25:52
2020/10/20 14:25:52 WARNING: Helm v3 configuration may be overwritten during this operation.
2020/10/20 14:25:52
[Move config/confirm] Are you sure you want to move the v2 configuration? [y/N]: y
2020/10/20 14:25:57
Helm v2 configuration will be moved to Helm v3 configuration.
2020/10/20 14:25:57 [Helm 2] Home directory: /Users/technosophos/.helm
2020/10/20 14:25:57 [Helm 3] Config directory: /Users/technosophos/Library/Preferences/helm
2020/10/20 14:25:57 [Helm 3] Data directory: /Users/technosophos/Library/helm
2020/10/20 14:25:57 [Helm 3] Cache directory: /Users/technosophos/Library/Caches/helm
2020/10/20 14:25:57 [Helm 3] Create config folder "/Users/technosophos/Library/Preferences/helm" .
2020/10/20 14:25:57 [Helm 2] repositories file "/Users/technosophos/.helm/repository/repositories.yaml" will copy to [Helm 3] config folder "/Users/technosophos/Library/Preferences/helm/repositories.yaml" .
2020/10/20 14:25:57 [Helm 3] Create cache folder "/Users/technosophos/Library/Caches/helm" .
2020/10/20 14:25:57 [Helm 3] Create data folder "/Users/technosophos/Library/helm" .
2020/10/20 14:25:57 [Helm 2] plugins "/Users/technosophos/.helm/cache/plugins" will copy to [Helm 3] cache folder "/Users/technosophos/Library/Caches/helm/plugins" .
2020/10/20 14:25:57 [Helm 2] plugin symbolic links "/Users/technosophos/.helm/plugins" will copy to [Helm 3] data folder "/Users/technosophos/Library/helm" .
2020/10/20 14:25:57 [Helm 2] starters "/Users/technosophos/.helm/starters" will copy to [Helm 3] data folder "/Users/technosophos/Library/helm/starters" .If you are satisfied with what you see being moved, remove the --dry-run flag and run the move.
In Matt Butcher's talk, he shared how releases used to be stored in kube-system using one format,
and are now stored in other namespaces using a different format.
In this step, we will run the converter to migrate those releases.
We know we have some releases in Helm 2:
$ helm2 list
NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE
drupal 1 Tue Oct 20 20:39:09 2020 DEPLOYED drupal-9.1.0 9.0.7 default
wordpress 1 Tue Oct 20 20:39:48 2020 DEPLOYED wordpress-9.8.0 5.5.1 default
$ Let's look at the releases helm3 currently knows about:
$ helm3 ls
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSIONYou should see an empty list. This is because Helm 3 cannot see releases created by Helm 2. The releases are in different formats (and in different namespaces).
We can use the 2to3 plugin to convert them. Again, we will dry-run first:
$ helm3 2to3 convert wordpress --dry-run
2020/10/20 15:33:51 NOTE: This is in dry-run mode, the following actions will not be executed.
2020/10/20 15:33:51 Run without --dry-run to take the actions described below:
2020/10/20 15:33:51
2020/10/20 15:33:51 Release "wordpress" will be converted from Helm v2 to Helm v3.
2020/10/20 15:33:51 [Helm 3] Release "wordpress" will be created.
2020/10/20 15:33:51 [Helm 3] ReleaseVersion "wordpress.v1" will be created.Remove the --dry-run and perform the actual migration.
$ helm3 2to3 convert wordpressNow running helm3 ls should show the Wordpress release:
$ helm3 list
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
wordpress wordpress 1 2020-10-20 20:09:50.7562551 +0000 UTC deployed wordpress-9.8.0 5.5.1 Repeat the process for the drupal release.
WARNING: This will delete both local and remote data. You may want to skip this step
or just do the --dry-run to see how it would work.
As a last step, you can delete Helm v2 configuration, Helm v2 releases and even tiller itself.
To cleanup Helm v2 completely, run helm3 2to3 cleanup.
To delete Helm v2 releases only, use the 2to3 plugin's cleanup command.
$ helm3 2to3 cleanup --release-cleanup --dry-run
2020/10/20 15:41:36 NOTE: This is in dry-run mode, the following actions will not be executed.
2020/10/20 15:41:36 Run without --dry-run to take the actions described below:
2020/10/20 15:41:36
WARNING: "Release Data" will be removed.
This will clean 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 may not be usable afterwards.
[Cleanup/confirm] Are you sure you want to cleanup Helm v2 data? [y/N]: y
2020/10/20 15:41:39
Helm v2 data will be cleaned up.
2020/10/20 15:41:39 [Helm 2] Releases will be deleted.
2020/10/20 15:41:39 [Helm 2] ReleaseVersion "drupal.v1" will be deleted.
2020/10/20 15:41:39 [Helm 2] ReleaseVersion "wordpress.v1" will be deleted.The output above indicates what will be deleted.
If you JUST want to uninstall Tiller and leave the releases alone, you can run helm3 2to3 cleanup --tiller-cleanup.