Error: This instance contains workspaced entities that need a custom migration in Helm upgrade

TL;DR

Why does my Helm upgrade fail with This instance contains workspaced entities that need a custom migration?

If this error appears during a helm upgrade, it usually means you are using an older Helm chart version. Update the Helm repo locally with helm repo update, then rerun the upgrade.

Problem

When running a Helm upgrade, you encounter the following error:

This instance contains workspaced entities that need a custom migration.
please use the provided helpers to migrate them:
kong migrations upgrade-workspace-table vaults_beta
Error: nginx not running in prefix: /tmp/tmp.okiPjN Run with --v (verbose) or --vv (debug) for more details

Solution

  1. Make sure the Helm repo is updated locally:

    helm repo update
  2. Then proceed with the Helm upgrade:

    helm upgrade kong-test -f values.yaml kong/kong --set migrations.preUpgrade=true --set migrations.postUpgrade=false

You can find more information about the Helm upgrade in the Kong Helm Chart documentation.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!