Manage Private Nodes
Upgrade vCluster​
Upgrade vCluster control plane​
Do not upgrade multiple minor versions at the same time for the control planeControl PlaneThe container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers. In vCluster, each tenant cluster has its own control plane components. as outlined in the Kubernetes Version Skew Policy. Instead always upgrade a single minor version, wait until the cluster becomes healthy and then upgrade to the next minor version. For example: v1.26 -> v1.27 -> v1.28.
To upgrade the vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs. control plane, update the Kubernetes init container version in your vcluster.yaml file.
After the change, vCluster upgrades the control plane automatically. If automatic worker node upgrades are configured, those nodes are also upgraded.
To change the Kubernetes version, add the following to your vcluster.yaml:
...
controlPlane:
statefulSet:
image:
tag: v1.31.1 # Or any other Kubernetes version
...
Upgrade vCluster workers​
Use the Kubernetes Version Skew Policy for worker upgrades.
There are two modes of how worker upgrades can be done:
- (Recommended) Automatically by vCluster when the control-plane was updated
- Manually using vCluster CLI or kubeadm
Use automatic upgrades​
Automatic worker node upgrades are enabled by default. vCluster upgrades each node when it detects a version mismatch between the control plane and the worker node. By default, one node is upgraded at a time. Upgrade starts 2 minutes after the control plane is upgraded. There is also a grace period for newly added worker nodes (upgrade is not going to start if node was created less than 2 minutes ago).
You can exclude a node from automatic upgrade by labeling it with vcluster.loft.sh/skip-auto-upgrade: true
The upgrade Pod runs directly on the node and completes the following steps:
- Downloads the Kubernetes binary bundle from the vCluster control plane.
- Replaces the
kubeadmbinary. - Runs
kubeadm upgrade node. - Cordons the node.
- Replaces other binaries such as
containerd,kubelet, and so on. - Restarts
containerdandkubeletif necessary. - Uncordons the node.
Node upgrades typically do not restart pods. However, depending on the Kubernetes version change, restarts might occur in some cases.
Perform manual upgrades​
You can either upgrade a node using the vCluster CLI by running the following command:
vcluster node upgrade my-node
Alternatively, you can manually upgrade by following the official Kubeadm Kubernetes guide.
Node profiles​
A node that joined with a node profile stays in sync with that profile for as long as it's part of the tenant clusterTenant clusterA fully isolated Kubernetes environment provisioned for a single tenant. Each tenant cluster has its own API server, controller manager, and resource namespace, backed by a virtualized control plane hosted on a control plane cluster. From the tenant's perspective it behaves exactly like a standard Kubernetes cluster.. Edits to the profile converge onto every node referencing it, and removed keys are pruned, except startupTaints, which apply only at join. See Continuous reconciliation for the full behavior.
Convergence is prompt rather than tied to a polling interval, so edits are typically reflected within moments in kubectl get node <node-name> -o yaml.
Reuse a node​
A node can be re-used for another tenant cluster by using the --force-join flag. Before joining the node to a new vCluster, it
should be deleted from the original vCluster.
# Delete the node from vCluster
vcluster node delete my-node
# Create a new token from the vCluster you want to join
vcluster token create
# Then on the node itself run this to join it
curl ... | sh -s -- --force-join
If you are re-oining the original vCluster, then the kube-flannel and kube-proxy pods are restarted. All workloads will be restarted.
Remove vCluster​
When deleting a vCluster with private nodes, it's recommended that each node is removed from the vCluster before deleting the vCluster itself.
Remove worker node​
To remove a node from the cluster, follow standard procedures as with any other Kubernetes distro. First cordon a node, then drain it, which can be done using kubectl commands. We supply a vCluster CLI command to delete worker nodes from the cluster.
vcluster node delete <node-name>
If you shut down, delete or otherwise make the node instance unreachable before running vcluster node delete, it will
prevent draining. To proceed, add --drain=false to the delete command.
Clean up orphaned node​
There may be cases where the vCluster is deleted before all worker nodes were removed.
In these scenarios, the kubelet, kube-proxy and other components running on the node are still trying to connect to the now deleted vCluster control plane.
The node can be cleaned up by using any join script with the --reset-only flag.
Cleaning up control-plane node can be done by running /var/lib/vcluster/node/join.sh --reset-only
Load Docker images to a node​
There may be instances where you want to load an image directly to the private node.
Before loading any images to the node, the node has to be in a Ready state and part of a tenant cluster. The command pulls the image locally
onto the machine that is running the command and saves it as a .tar archive. It creates a pod on the private node and copies the image using kubectl cp to the pod. The pod imports the image onto the node.
vcluster node load-image my-node --image nginx:latest