Skip to main content

Upgrade Guide from pre-v4.0 to v4.0+

These docs cover upgrading from pre v4.0 to v4.0. Once you upgrade to v4.0+, you need to follow the regular upgrade docs.

Upgrade to the latest Loft v3.x version​

Before attempting to perform this major upgrade, upgrade to the latest v3.x version. Review the older upgrade docs on how to upgrade. It is recommended to upgrade using the CLI and not the UI as there are known issues to upgrade versions through the UI.

Pre-Upgrade Recommendations​

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.

vCluster versions are required on virtual clusters and virtual cluster templates​

One of the breaking changes in v4.0 is the requirement of a vCluster version defined on your virtual cluster. Previously if you deployed a vCluster version or used a vCluster version without editing the version field, the version was not set in the spec of the resource. With each upgrade of the Platform, the vCluster would automatically upgrade these virtual clusters to the latest default vCluster version. Due to the breaking changes introduced in v0.20, automatic upgrades of vCluster version are no longer supported and a vCluster version must be set in the spec of a virtual cluster or virtual cluster template.

We recommend confirming that the versions of your virtual clusters and virtual cluster templates are in the resource yaml before upgrading. Otherwise, your virtual clusters will have errors requiring you to define these versions post upgrade and since it will not know what version you upgraded from, it will not know what version to set and manual steps will need to happen to determine the correct version and set it.

How to define the vCluster version on Existing Virtual Clusters​

In the UI, for each virtual cluster, edit the configuration and type the version of the virtual cluster or virtual cluster template in the textbox and the resource yaml will automatically update the spec to include the version.

If the resource yaml of your virtual cluster or virtual cluster template has spec.template.helmRelease.chart.version set, then the virtual cluster version is defined.

spec Example:

spec:
  template:
    helmRelease:
      chart:
        version: 0.19.7

Download the latest vCluster CLI (v0.20.0+)​

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

Required Changes in your Platform Configuration before Upgrading​

A new feature has been added to support the ability to change the prefix of the namespace created for projects. In previous versions, the prefix was loft-p, but in v4.0.0, the new default is p-. Due to the change in defaults, the previous prefix needs to be set in the Platform configuration as part of the upgrade command. Since future upgrades reuse the values of the configuration, you only need to apply it once.

Appending the project prefix to upgrade commands​

To upgrade the 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.

PLATFORM_NAMESPACE="loft" # update if the platform is installed to a different namespace
PLATFORM_VERSION="" # specify a version or it will upgrade to latest stable

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

Adding the project prefix to your values file​

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

config:
  projectNamespacePrefix: loft-p-

Post-Upgrade Recommendations​

Migrating 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 woulld 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. These new OIDC clients can be managed either 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 will be removed in version 5.0.

Migrating 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 discard once all steps have been succesful.
  9. Delete the oidc.clients field. This will cause vCluster Platform to restart.
  10. Validate OIDC clients function normally.

Troubleshooting Tips​

Forgot the Project Prefix​

If you accidentially performed the upgrade without setting the projectNamespacePrefix, then the pod of the platform will be in a CrashLoopBackoff with 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"}

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