Skip to main content
Version: v4.12 Stable

Upgrade from v3 to v4

Who needs this page

This page only applies if you're upgrading vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs.Related: Tenant cluster, Control plane cluster Platform from a v3.x release to v4.0. If you're already running v4.0 or later, use the regular upgrade instructions instead.

Before attempting this major upgrade, upgrade to the latest v3.x version first. Review the older upgrade docs on how to upgrade. Upgrade using the CLI and not the UI, since there are known issues upgrading versions through the UI.

Pre-upgrade recommendations​

  1. Read through the v4.0 release notes. Review the release notes for v4.0 to read the updates in the release and understand any behavior changes.

  2. vCluster versions are required on tenant clusters and tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.Related: Control plane cluster, Tenant cluster templates. One of the breaking changes in v4.0 is the requirement of a vCluster version defined on your tenant cluster. Previously, if you deployed a tenant cluster without editing the version field, the version wasn't set in the spec of the resource. With each upgrade of the platform, these tenant clusters were automatically upgraded to the latest default vCluster version. Due to the breaking changes introduced in v0.20, automatic upgrades of the vCluster version are no longer supported. You must set a vCluster version in the spec of each tenant cluster and tenant cluster template.

    Confirm that the resource YAML includes the versions of your tenant clusters and tenant cluster templates before upgrading. Otherwise, your tenant clusters might encounter errors that require you to define these versions after the upgrade. The platform can't detect which version you upgraded from, so it can't set the correct version automatically. You must determine and set it manually.

  3. Define the vCluster version on existing tenant clusters. In the UI, edit each tenant cluster or tenant cluster template and type the version in the version field. The resource YAML automatically updates the spec to include it. If the resource YAML already has spec.template.helmRelease.chart.version set, the version is defined.

    Example of spec
    spec:
        template:
            helmRelease:
              chart:
                version: 0.19.7

Download the latest vCluster CLI​

With the deprecation of the Loft CLI, review the Loft CLI to vCluster CLI Migration docs.

Required changes in your platform configuration before upgrading​

v4.0 adds the ability to change the prefix of the namespaces created for projects. In previous versions the prefix was loft-p-, and in v4.0.0 the new default is p-. Because the default changed, you must set the previous prefix in the platform configuration as part of the upgrade command. Future upgrades reuse the configuration values, so you only need to set it once.

Append the project prefix to upgrade commands​

To upgrade from v3 to v4 using the vCluster CLI, run the following. The command pins v4.0.0, the target of this upgrade:

Platform Namespace

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.

PLATFORM_NAMESPACE="loft" # Update if the platform is installed to a different namespace
PLATFORM_VERSION="4.0.0"

vcluster platform start --upgrade --namespace $PLATFORM_NAMESPACE --version=$PLATFORM_VERSION --values=<(cat <<EOF
config:
  projectNamespacePrefix: loft-p-
EOF
)

Add the project prefix to your values file​

If you upgrade the Platform with another method, an alternative is to extend your config file and include the project prefix requirement for this upgrade.

config:
  projectNamespacePrefix: loft-p-

Post-upgrade recommendations​

Migrate vCluster Platform OIDC provider clients​

vCluster Platform can be used as an OIDC provider. Formerly, to add clients to the vCluster Platform OIDC provider a user would add them to the oidc.clients array field in the vCluster Platform config. This could be done either through the Admin > Config UI or through editing the loft-manager-config secret found in the namespace vCluster Platform is installed in. Editing this config causes loft to restart, which should be unnecessary for adding OIDC platform clients. Therefore, managing vCluster Platform OIDC clients has been moved to its own UI, and the clients their own objects. You can manage these OIDC clients through the OIDC Provider tab of the admin page or through Kubernetes Secrets. See Adding OIDC Clients to vCluster Platform OIDC Using Secrets. The oidc.clients field is deprecated in vCluster Platform version 4.0 and is removed in version 5.0.

Migrate OIDC clients from admin config to new OIDC clients​

  1. Navigate to Admin > OIDC Provider.
  2. Select Add Client.
  3. In a separate tab navigate to Admin > Config.
  4. Copy over the name, clientID, and clientSecrets fields from the first element of oidc.clients to the open editor on the OIDC Provider page.
  5. Copy each value from the oidc.clients.redirectURIs list to the Allowed redirect URIs editor field on the OIDC Provider page. Separate each URI by a newline.
  6. Select "Save".
  7. Repeat steps 1-6 for all clients.
  8. Copy the oidc.clients to a safe location. These can be discarded once all steps have been successful.
  9. Delete the oidc.clients field. This causes vCluster Platform to restart.
  10. Validate OIDC clients function normally.

Troubleshoot​

Forgot the project prefix​

If you accidentally performed the upgrade without setting the projectNamespacePrefix, then the pod of the platform is in a CrashLoopBackoff with a log similar 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"}

Follow the instructions on how to append the project prefix and upgrade again.