v0.19 to v0.20 Conversion Guide

As part of the v0.20.0 release, Loft Labs introduced a new vcluster.yaml configuration file with a new structure. This file replaces your existing values.yaml configuration file. Pre-v0.20.0 values.yaml files are not compatible with v0.20.0. You need to convert to the new format in order to use the new vCluster CLI and upgrade existing vCluster instances.

Upgrade vCluster v0.19 to v0.20+ by following these steps:

1. Upgrade the vCluster CLI.
2. Convert your Helm values configuration file to the new vcluster.yaml configuration file.
3. Use your new vcluster.yaml file to upgrade your vCluster instance.

Beta Release

vCluster v0.20.0 is currently in beta. This version contains most of the major features, but is not yet complete. It is intended to give an early preview and gather feedback from our users. Loft Labs strongly discourages using v0.20.0 in production environments. There will be a GA release after Loft Labs has received input and matured the v0.20 release stream.

View the v0.20.0-beta.1 release notes.

Supported legacy versions

Loft Labs has tested the conversion path from v0.19.x to v0.20.0 and therefore recommends moving to v0.19.x before converting to v0.20.0.

Conversions from vCluster versions prior to 0.19.x might work but have not been tested extensively.

Before you begin

The required Helm version is >= v.3.10.0.

Hostpath Mapper

Upgrade vcluster-hostpath-mapper to v0.1.1-beta.1 or later for use with the new vcluster.yaml configuration file in v0.20.

Upgrade the CLI

Before upgrading virtual cluster instances, upgrade to the latest version of the vCluster CLI.

vcluster upgrade --version v0.20.0-beta.1

VCLUSTER Flags

The v0.20.0 vCluster CLI release dropped several flags in favor of vcluster.yaml configuration. View the release notes to see the discontinued flags.

The v0.20.x vCluster CLI has been extended to support converting from the old values.yaml format to the new vcluster.yaml by adding a vcluster convert config command.

Usage:
  vcluster convert config [flags]
Flags:
      --distro string   Kubernetes distro used
  -f, --file string     Path to the input file
  -h, --help            Help for config
  -o, --output string   Prints the output in the specified format. Allowed values: yaml, json (default "yaml")

Convert your values.yaml to vcluster.yaml

Convert to the new vcluster.yaml configuration file format by running:

vcluster convert config --distro KUBERNETES_DISTRO -f VALUES_FILE > vcluster.yaml

Replace:

• KUBERNETES_DISTRO with your virtual cluster's existing Kubernetes distribution. You can't change the Kubernetes distribution or backing store during an upgrade.
• VALUES_FILE with the path to the values.yamlfile you used to configure your pre-v0.20 vCluster instance.

For example:

vcluster convert config --distro k8s -f /my/k8s/values.yaml > vcluster.yaml

If you don’t have your configuration values, use Helm to retrieve those for your currently running virtual cluster.

helm get values VCLUSTER_NAME -n VCLUSTER_NAMESPACE

Replace:

• VCLUSTER_NAME with the name of your vCluster instance.
• VCLUSTER_NAMESPACE with the namespace that vCluster runs in.

This uses --revision 0 under the hood. Adjust this accordingly to receive the values of your latest revision. See the Helm docs for how to fetch revision history.

Upgrade your vCluster instance

Downgrading vCluster instances is NOT supported

While downgrading to an older version of the vCluster CLI is supported, you cannot downgrade virtual cluster instances to a prior version of vCluster (for example, from 0.20 back to 0.19). Make sure you have tested the upgrade sufficiently before rolling out this change to critical systems.

vCluster CLI

vcluster create --upgrade VCLUSTER_NAME -n VCLUSTER_NAMESPACE -f vcluster.yaml

Replace:

• VCLUSTER_NAME with your vCluster instance name.
• VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

Helm

helm upgrade --install VCLUSTER_NAME vcluster \
  --values vcluster.yaml \
  --repo https://charts.loft.sh \
  --namespace VCLUSTER_NAMESPACE \
  --repository-config=''

Replace:

• VCLUSTER_NAME with your vCluster instance name.
• VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

kubectl

helm template VCLUSTER_NAME vcluster --repo https://charts.loft.sh -n VCLUSTER_NAMESPACE -f vcluster.yaml | kubectl apply -f -

Replace:

• VCLUSTER_NAME with your vCluster instance name.
• VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

Terraform

Apply vCluster config changes by editing the vcluster.yaml file and running terraform plan:

terraform plan

Review the planned changes and apply them if they look appropriate:

terraform apply

Argo CD

Add your vcluster.yaml config file to the valueFiles array in your ArgoCD Application file.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: VCLUSTER_NAME
  namespace: argocd
spec:
  project: default
  source:
    chart: vcluster
    repoURL: https://charts.loft.sh
    helm:
      releaseName: VCLUSTER_NAME
      valueFiles:
        - vcluster.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: VCLUSTER_NAMESPACE

Replace:

• VCLUSTER_NAME with your vCluster instance name.
• VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

Cluster API

Apply Cluster API changes by regenerating the cluster custom resource using clusterctl.

export CLUSTER_NAME=VCLUSTER_NAME
export CLUSTER_NAMESPACE=VCLUSTER_NAMESPACE
export KUBERNETES_VERSION=1.29.3
export HELM_VALUES=$(cat vcluster.yaml)

clusterctl generate cluster ${CLUSTER_NAME} \
    --infrastructure vcluster \
    --kubernetes-version ${KUBERNETES_VERSION} \
    --target-namespace ${CLUSTER_NAMESPACE} | kubectl apply -f -

Replace:

• VCLUSTER_NAME with your vCluster instance name.
• VCLUSTER_NAMESPACE with the namespace where you deployed vCluster.

After the changes have been applied, wait for the vCluster custom resource to report a ready status:

kubectl wait --for=condition=ready vcluster -n $CLUSTER_NAMESPACE $CLUSTER_NAME --timeout=300s

How to downgrade the vCluster CLI

Similar to upgrading the CLI, you can go back to a prior vCluster CLI version by running:

vcluster upgrade --version v0.19.5

Related content

• View the v0.20.0-beta.1 release notes.
• Quick Start Guide to learn how to use the new config file.
• vCluster config reference for configuration details.