Skip to main content

Upgrade vCluster Platform

Upgrading vCluster Platform is easy! vCluster Platform can be upgraded either via the vCluster CLI, or with Helm.

Upgrade vCluster Platform via:

To upgrade vCluster Platform via vCluster CLI, update $PLATFORM_VERSION with a valid vCluster Platform version and run:

vcluster platform start --upgrade --version=$PLATFORM_VERSION --values=vcluster-platform.yaml
Versions and Values

The $PLATFORM_VERSION variable above is an environment variable set to your desired vCluster Platform version to deploy. The vcluster-platform.yaml file is an optional YAML file that contains Helm values you would like to use when upgrading your vCluster Platform deployment.

Upgrading from v3.x to v4.0​

Upgrade to latest v3 first

Before attempting to perform this major upgrade please ensure that you have upgraded to the latest v3 release first. E.g. by running the steps above.

Only vCluster CLI is supported

If you choose to upgrade vCluster Platform via the CLI it is required to use the vcluster CLI and not the loft CLI. For further information please see the Loft CLI to vCluster CLI Migration section.

With v4.0 the project namespace prefix can now be configured and the default has been changed from loft-p (which is used by v3) to p-. In order for the upgrade from v3 to v4 to succeed you must set this explicitly regardless of updating via the vCluster CLI or via Helm.

Upgrade vCluster Platform from v3 to v4 via:

To upgrade vCluster Platform from v3 to v4 via vCluster CLI, run. Update $PLATFORM_VERSION with a valid vCluster Platform version.

Plaftorm Namsespace

The following steps assume the existing installation is in the default namespace loft. The default namespace for v4 is vcluster-platform, so we specify the namespace in the steps.

# First set the project namespace prefix to use the v3 format
cat > /tmp/vcluster-platform.yaml <<EOF
config:
  projectNamespacePrefix: loft-p-
EOF

vcluster platform start --namespace loft --upgrade --version=$PLATFORM_VERSION --values=/tmp/vcluster-platform.yaml

If you accidentially performed the upgrade without setting the projectNamespacePrefix to the above mentioned value the vCluster platform Pod will be in a CrashLoopBackoff showing a log similiar to:

cmd/main.go:107 error executing root command    {"component": "loft", "error": "init (4): set default project namespace prefix: seems like you have upgraded the platform from an earlier version that uses 'loft-p-' as a project namespace prefix. This has been changed to be 'p-' in the current version. Please set 'projectNamespacePrefix: loft-p-' in the platform config to get rid of this error"}

In that case wait until the Pod starts up again and retry the above upgrade command by passing along a vcluster-platform.yaml file that contains the config change.