A plugin to migrate user-specified Helm values between chart versions when the schema of values.yaml
changes. Define migration paths with migration files in the chart repository to ensure seamless upgrades.
- Helm version 3 or newer
- Git if installing using the
helm plugin install
command below
$ helm plugin install https://github.com/OctopusDeploy/helm-migrate-values.git
This Helm plugin enables users to migrate values across chart versions, accounting for changes in the values.yaml schema.
NOTE: The intended usage of this plugin is that it does not apply any changes to the release on its own. It simply outputs the values to override, which are to be used with
helm upgrade --reset-then-reuse-values
.See output values section for an example on how to apply the migration to a release
Start by defining the migration files within your Helm chart. These files should be placed under the value-migrations/
directory, relative to your base chart directory. You can customize the migration directory location by using the --migration-dir
flag if necessary.
Each migration file should conform to the following naming format:
to-v{VERSION_TO}.yaml
, where VERSION_TO is the target chart's major version number. The plugin will use this file to define the transformation between the previous version and the specified version.
Migration files are written in YAML and use Go templating, similar to Helm templates. They leverage Sprig v3's TxtFuncMap functions for transforming and mapping values between old and new schemas. See this example of a migration definition from the integration test.
To migrate your Helm release to a new chart version, use the following command:
helm migrate-values [RELEASE] [CHART] [flags]
- RELEASE: The name of the Helm release you're migrating.
- CHART: The chart you're migrating to, which can be a local chart (specified by file path) or a remote chart (using the
oci://
orhttps://
prefixes).
helm migrate-values my-kubernetes-agent oci://registry-1.docker.io/octopusdeploy/kubernetes-agent \
--version 2.4.0 \
-n octopus-agent-demo \
--migration-dir kubernetes-agent/value-migrations
--output-file migrated-values.yaml
The --output-file
flag allows you to optionally save the command's output to a file instead of displaying it in stdout, allow you to utilize it in subsequent Helm commands.
You can then use this file with the helm upgrade command to complete the migration:
helm upgrade [RELEASE] [CHART] -f migrated-values.yaml --reset-then-reuse-values
Please refer to the Code of Conduct before making any contributions.
We adhere to Semantic Versioning and utilize @changesets/cli to manage release notes and versioning.
To add a changelog entry for your changes:
- Run the following command:
npm run changeset
- Select the appropriate version type for your changes (patch, minor, or major).
- Provide a brief description of the changes you've made.
This will generate a changeset file, which must be included in your pull request.