Skip to main content
Version: 3.4

Upgrade v2 to v3

This guide briefly covers a few topics that Loft admins may wish to review before upgrading to Loft version 3. We recommend taking a look at the topics in this section to ensure that you are getting the best experience with Loft version 3.

Setting loftHost in the loft config

Please make sure to set loftHost: as we have changed the way Loft and the Loft agent communicate with v3. We have a fallback in place that works for most public clusters, but for private clusters you will need to make sure your Loft host is configured correctly.

Breaking Changes in Loft v3

  • We removed all kiosk apis that were deprecated in Loft v2, please use the new project api instead. This includes:
    • Account
    • Security Templates
    • Cluster Account Templates
  • loft sleep is now loft sleep space
  • loft wakeup is now loft wakeup space
  • Grafana integration was removed. We felt that this wasn't providing much benefit and users rarely used this. Please use Grafana directly if you were using this.
  • Template syncing in non project spaces / virtual clusters was removed, please import the spaces / virtual clusters into a project to sync the templates
  • Space Constraints are now deprecated, please use projects instead

New Objects

One of the biggest changes in Loft version 3 is the addition of new object types. Take a quick read through the following sections (and the linked sections!) to get a feel for the most important new objects.


Projects are an organizational unit in Loft, they are a place for you to group your resources, in Loft 3, you will almost certainly want to be working with Projects as they give you a simpler mechanism for applying policies to your resources.

Check out the "What Are Projects?" documentation here for more information.

Space and Virtual Cluster Instances

Space and Virtual Cluster instances are a new resource that further abstracts the space and virtual cluster types. The instance type contains not only information about the space or virtual cluster, but also information about which connected cluster the space or virtual cluster resides in. In general, you will want to migrate your spaces and virtual clusters to the new instance type, this process is outlined below in the Import Legacy Spaces and Import Legacy Virtualclusters sections.

This makes it possible to give users only access to a virtual cluster without giving them any access to the host cluster.

A New Project

One of the first things you may want to do when getting settled in with Loft version 3 is to create a new Project. You can use the default "Default" project of course, but we generally advise Loft admins to create projects that are meaningful to them and their environment rather than simply using the default/placeholder project.

Read about creating projects here.

Import Legacy Spaces

Legacy spaces can be imported into the new improved space instance type from the Loft UI or via the Loft CLI. One advantage of importing legacy spaces is that they will properly show up in your desired Project (as spaceinstances are always associated with a project!).

The process for importing legacy spaces is documented here.

Import Legacy Virtual Clusters

Just like legacy spaces, legacy virtualclusters can be imported into a project. It is a good idea to get this done after the upgrade process!

Follow the documentation here to import legacy virtual clusters.

Managing Loft Config

In Loft version 2, it was necessary to manage the loft-config secret separately from the helm release. In Loft version 3, config can now be managed using the helm values. For more information about managing the config via helm, see Changing Loft Config.

GitOps managed Loft Config

If you are managing the loft-config secret using GitOps (via terraform or ArgoCD, for example), it is encouraged that you use the helm values for managing config in Loft version 3. Loft will migrate the config secret to loft-manager-config and remove the loft-config secret upon start up, causing the GitOps state to become out of sync. Using the helm chart values to manage configuration will avoid this issue.