Proposal: Migrate Helm v2 releases in-place to v3

[hickeyma]

1. Overview

Helm v3 introduces quite a lot of change in the underlying architecture and plumbing from the previous release, Helm v2. One key change is around Release storage. The changes includes the Kubernetes resource for storage and the release object metadata contained in the resource. Releases will also be on a per user namespace instead of using the the Tiller namespace (for example, v2 default Tiller namespace kube-system).

2. Use case

When Helm v3 is installed in a cluster that is currently managed by a Helm v2 installation, a common requirement will be to migrate releases in-place to Helm v3 (i.e. without deleting and re-deploying them).

Note: This proposal covers the migration use case of Helm v3 managing existing Helm v2 releases (i.e. converting v2 releases to v3 releases). Other migration use cases are covered by documentation: #5582.

3. Proposal

1. Get v2 release versions Secrets or ConfigMaps
2. For each release version:
   • Map v2 release version object to v3 release object
   • Add this v3 release object to Helm v3
3. Delete the v2 release versions as Secrets or ConfigMaps

Note:

• The namespace is based off each v2 release version namespace
• When adding v3 release version, only the release object is added and not the underlying kubernetes resources
• When deleting v2 release , only the release (and history) is deleted and not the underlying kubernetes resources
• It is assumed that all v2 release versions are incremental and in order, and that the versions can be added incrementally as well

3.1 Implementation

A standalone migration tool that migrates from Helm v2 to Helm v3. (@prydonius
helm/community#67 (comment))

The primary function of the tool is to:

• Automatically back up Helm v2 Release and convert them to Helm v3 Release

The suggestion is for a simple, Helm-org supported plugin named helm 2to3. The plugin should concentrate at the start on its primary function of converting releases from v2 to v3 through the convert subcommand. It should be able to be extended if need be. (@jdolitsky helm/community#67 (comment))

$ helm 2to3 convert myrelease --dry-run
NOTE: This is in dry-run mode, the following actions will not be executed.
Run without --dry-run to take the actions described below:

Release "myrelease" will be converted from Helm 2 to Helm 3.
[Helm 3] Release "myrelease" will be created.
[Helm 3] ReleaseVersion "myrelease.v1" will be created.
[Helm 3] ReleaseVersion "myrelease.v2" will be created.
[Helm 2] Release "myrelease" will be deleted.
[Helm 2] ReleaseVersion "myrelease.v1" will be deleted.
[Helm 2] ReleaseVersion "myrelease.v2" will be deleted.

$ helm 2to3 convert myrelease
Release "myrelease" will be converted from Helm 2 to Helm 3.
[Helm 3] Release "myrelease" will be created.
[Helm 3] ReleaseVersion "myrelease.v1" will be created.
[Helm 3] ReleaseVersion "myrelease.v1" created.
[Helm 3] ReleaseVersion "myrelease.v2" will be created.
[Helm 3] ReleaseVersion "myrelease.v2" created.
[Helm 3] Release "myrelease"  created.
[Helm 2] Release "myrelease" will be deleted.
[Helm 2] ReleaseVersion "myrelease.v1" will be deleted.
[Helm 2] ReleaseVersion "myrelease.v1" deleted.
[Helm 2] ReleaseVersion "myrelease.v2" will be deleted.
[Helm 2] ReleaseVersion "myrelease.v2" deleted.
[Helm 2] Release "myrelease"  deleted.
Release "myrelease" was converted successfully from Helm 2 to Helm 3. 

4. Reference

• Migration was raised at KubeCon/CloudNativeCon Seattle 2018 at the Helm Deep Dive session.
  Ref: helm 2 to helm 3 upgrade story community#67.

• @maorfr helm-plugin-utils and helm-backup

[hickeyma]

First shot at this folks. Appreciate your comments.

/cc @adamreese @bacongobbler @mattfarina @michelleN @prydonius @SlickNik @technosophos @thomastaylor312 @jdolitsky @henrynash @rimusz

[bacongobbler]

+1 to writing this as a standalone project.

Re-using related backup and restore tools like helm-backup and helm-restore would be useful here as it would cut down on development time significantly. You could probably re-use helm-backup as-is and just write the equivalent of a helm-restore for migrating Helm 2 releases to Helm 3.

cc @maorfr

[thomastaylor312]

I am not entirely sure on what these three points in section 3.2 are referring to:

A flag (e.g. --state-only) in v3 release upgrade which only adds the release object and not the undelying kubernetes resources
A flag (e.g. --state-only) in v2 release delete which only deletes the release object (and history) and not the undelying kubernetes resources

Isn't the goal of the tool to not modify the current state of the Kubernetes resources as stated in section 3? Just want to make sure it is clear for those reading it

v3 helm upgrade --install flag seems to be disabled

As far as I know, --install does still work from my testing with v3. However, could you clarify how this relates to building this tool?

Otherwise, this is looking really great and straightforward

[rimusz]

+1 to reuse tools like helm-backup and helm-restore and it should only do the releases history migration not touching underlying kubernetes resources.

[hickeyma]

re #6154 (comment) Thanks @bacongobbler for "heads up" about tools from @maorfr. I will take a look and go for re-use where possible.

[hickeyma]

Isn't the goal of the tool to not modify the current state of the Kubernetes resources as stated in section 3?

@thomastaylor312 When doing PoC, I used the upgrade function to add the mapped v2 releases to v3. This function also adds the underlying Kubernetes resources. Do we have a function that just add the release only or do we need to update this function with a flag? Same applies for the v2 delete function.
Maybe there is a better way to do this?

I'll look again at --install option .

[thomastaylor312]

@hickeyma if you use the helm.sh/helm/pkg/storage package, it allows you to just save the release without the rest of the process of installing

[maorfr]

I would love to help on this effort!
@hickeyma feel free to involve me :)

[bacongobbler]

Yep. pkg/storage is where you want to look.

helm/pkg/storage/storage.go

Lines 50 to 52 in d360705

	// Create creates a new storage entry holding the release. An
	// error is returned if the storage driver failed to store the
	// release, or a release with identical an key already exists.

[hickeyma]

Deadly, thanks @thomastaylor312. Gotta love PoCing, nearly always taking the long road first!

[hickeyma]

Sure @maorfr, thanks. Let me get it kicked off first.

[hickeyma]

First draft of the plugin . Look forward to the feedback.

Note: It is still WIP and requires lot more testing. I just thought it was worth getting it out there to get some reviews on it.

[maorfr]

@hickeyma glad you found the plugin-utils useful! ;)

[hickeyma]

Nice work @maorfr. It helped simplify the implementation a lot. Let me know what you think and how we can improve it.

[rimusz]

@hickeyma
Regarding the Delete the v2 release versions as Secrets or ConfigMaps we should have an extra flag to keep the v2 release or vice versa to delete v2 release.
As well when all v2 releases are converted to v3, we can just delete all releases configmaps/secrets in tiller namespace.

[hickeyma]

@rimusz Good suggestion. How about a flag like --keep-v2-releases which is false by default? Should the delete all releases be part of the plugin or documentation on how to?

[rimusz]

+1 for the flag --keep-v2-releases and we should document that very clearly that by default v2 releases get deleted if that flag is not used.
I do not see a point for the delete all releases be part of the plugin, we should just document that option with good examples.

[hickeyma]

Re #6154 (comment) retain v2 releases, done: https://github.com/hickeyma/helm-2to3/issues/4

[hickeyma]

helm-2to3 plugin now moved to Helm Org.

[bacongobbler]

Closing this issue as resolved; let's follow up in the helm-2to3 plugin issue queue for any issues related to that project going forward. Thanks @hickeyma for leading the effort on this one! :)