Upgrade vCluster

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

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

vCluster CLI

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

vcluster upgrade --version <VCLUSTER_VERSION>
vcluster create --upgrade <VCLUSTER_NAME> -n <VCLUSTER_NAMESPACE> -f vcluster.yaml

Replace:

• <VCLUSTER_VERSION> with the version of vCluster that you want to upgrade to.
• <VCLUSTER_NAME> with the name of your vCluster.
• <VCLUSTER_NAMESPACE> with the namespace that is running the vCluster.

Helm

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

Replace:

• <VCLUSTER_VERSION> with the version of vCluster that you want to upgrade to.
• <VCLUSTER_NAME> with the name of your vCluster.
• <VCLUSTER_NAMESPACE> with the namespace that is running the vCluster.

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: <VCLUSTER_NAME>
     namespace: argocd
   spec:
     project: default
     source:
       chart: vcluster
       repoURL: https://charts.loft.sh
       targetRevision: <VCLUSTER_VERSION>
       helm:
         releaseName: <VCLUSTER_NAME>
         valueFiles:
           - vcluster.yaml
     destination:
       server: https://kubernetes.default.svc
       namespace: <VCLUSTER_NAMESPACE>

   Replace:

   • <VCLUSTER_NAME> with the name of your vCluster.
   • <VCLUSTER_VERSION> with the version of vCluster that you want to upgrade to.
   • <VCLUSTER_NAMESPACE> with the namespace that is running the 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.

    # Replace <VCLUSTER_NAME> and <VCLUSTER_NAMESPACE> with values of the vCluster that you are updating
    export CLUSTER_NAME=<VCLUSTER_NAME>
    export CLUSTER_NAMESPACE=<VCLUSTER_NAMESPACE>
   
    # Since the vcluster.yaml has changed, you'll need to re-export it to the updated vcluster.yaml
    export VCLUSTER_YAML=$(awk '{printf "%s\\n", $0}' vcluster.yaml)
    
    # Set what version of vCluster that you want to update to
    export CHART_VERSION=<VCLUSTER_VERSION>

   Replace:

   • <VCLUSTER_NAME> with the name of your running vCluster.
   • <VCLUSTER_NAMESPACE> with the namespace that is running the vCluster.
   • <VCLUSTER_VERSION> with the version of vCluster that you want to upgrade to.

3. Regenerate the manifest and apply the updated manifest.

    clusterctl generate cluster ${CLUSTER_NAME} \
      --infrastructure vcluster \
      --target-namespace ${CLUSTER_NAMESPACE} \
       | 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 $CLUSTER_NAMESPACE $CLUSTER_NAME --timeout=300s