Upgrade vCluster

At any time, you can upgrade the version of your vCluster. During the upgrade, you can also apply configuration option changes.

Upgrades should be done one minor version at a time. While larger jumps may be possible, we do not actively test or support this path. The following list represents known upgrade path concerns, but does not include all breaking changes:

• In v0.29 etcd was upgraded to v3.6. The upstream etcd docs state that before upgrading to v3.6, you must already be on v3.5.20 or higher, otherwise failures may occur. This version of etcd was introduced in vCluster v0.24.2. Ensure that you have upgraded to at minimum that version, before upgrading to v0.29.
• In v0.20, vcluster.yaml was introduced which replaced values.yaml, and a migration was required. See the following page for a guide on that path.

Update vcluster.yaml

Optionally, you can update your vcluster.yaml to change your configuration options during a vCluster version upgrade.

Limitations on changing configuration

You cannot change distros or backing store once a virtual cluster is deployed, with one exception: starting with vCluster 0.25.0, migration from K3s to K8s distro is supported. For more details, see the K3s to K8s Migration.

Upgrade vCluster version

These steps assume that you have been a vcluster.yaml, but there are variables in the code blocks for you to replace for:

• Name of the virtual cluster
• Namespace of where the virtual cluster is deployed
• Version to upgrade to

Modify the following with your specific values to replace on the whole page and generate copyable commands:

VCLUSTER_NAME

VCLUSTER_NAMESPACE

VCLUSTER_VERSION

vCluster CLI

Upgrade your CLI to the version of vCluster that you want to upgrade your virtual cluster to.

vcluster upgrade --version 0.30.0
vcluster create --upgrade myvcluster -n vcluster -f vcluster.yaml

Helm

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

Terraform

1. Generate a new plan.

   terraform plan

   Verify that the provider can access your cluster and that the proposed changes are correct.

2. Upgrade your vCluster.

   terraform apply

Argo CD

1. Update ArgoCD Application file to update the version that you want to upgrade to.

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

2. Commit and push this updated file to your configured ArgoCD repository.

   (Optional) Commit and push an updated vcluster.yaml file to your configured ArgoCD repository.

3. Synchronize your ArgoCD repository with your configured cluster.

Cluster API

Learn more about Cluster API Provider for vCluster.

1. Install the vCluster provider.

   clusterctl init --infrastructure vcluster:v0.2.0

2. Export environment variables to be used by the cluster API provider to create an updated manifest. The manifest will be applied to your Kubernetes cluster, which will update your vCluster with the updated configuration options.

    export VCLUSTER_YAML=$(awk '{printf "%s\\n", $0}' vcluster.yaml)

3. Regenerate the manifest and apply the updated manifest.

   clusterctl generate cluster myvcluster \
     --infrastructure vcluster \
     --target-namespace vcluster \
       | kubectl apply -f -

   Kubernetes Version

   The Kubernetes version for the vCluster is not set at the CAPI provider command. It is configured the vcluster.yaml file based on your Kubernetes distribution.

4. Wait for vCluster to be updated by watching for the vCluster custom resource to report a ready status.

   kubectl wait --for=condition=ready vcluster -n vcluster myvcluster --timeout=300s