Join Private Nodes

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

Private Nodes

Join worker nodes to the virtual cluster

Pre-requisites

• vCluster CLI installed on your local machine
• vCluster control plane has to be running and in Ready state
• A node that satisfies the node requirements

To join worker nodes, a token from the vCluster must be created to provide access and permissions. A single token can be used for any node(s) to join, or if you wanted to, you could create a token for each node.

By default, the token expires within 1 hour. The token is stored as a secret prefixed with bootstrap-token- in the kube-system namespace. The expiry timestamp is stored under the expiration key in the secret.

Create a token for worker nodes

export VCLUSTER_NAME=my-vcluster

# Connect to your vcluster
vcluster connect $VCLUSTER_NAME

# Create a token
vcluster token create --expires=1h

The output provides a command to run on your worker node:

Example output from creating a token

curl -sfLk https://<vcluster-endpoint>/node/join?token=<token> | sh -

For each worker node that you want to join vCluster, run the command on the worker node.

Example output on worker node

Preparing node for Kubernetes installation...
Kubernetes version: v1.31.2
Installing Kubernetes binaries...
Enabling containerd and kubelet...
Created symlink /etc/systemd/system/multi-user.target.wants/containerd.service → /etc/systemd/system/containerd.service.
Created symlink /etc/systemd/system/multi-user.target.wants/kubelet.service → /etc/systemd/system/kubelet.service.
Starting containerd and kubelet...
Installation successful!
Joining node into cluster...
[preflight] Running pre-flight checks
[preflight] Reading configuration from the cluster...
[preflight] FYI: You can look at this config file with 'kubectl -n kube-system get cm kubeadm-config -o yaml'
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/config.yaml"
[kubelet-start] Writing kubelet environment file with flags to file "/var/lib/kubelet/kubeadm-flags.env"
[kubelet-start] Starting the kubelet
[kubelet-start] Waiting for the kubelet to perform the TLS Bootstrap...

This node has joined the cluster:
* Certificate signing request was sent to apiserver and a response was received.
* The kubelet was informed of the new secure connection details.

Run 'kubectl get nodes' on the control-plane to see this node join the cluster.

Available flags to use in the script to join nodes

The output of creating the token outputs a script to join the worker node to the vCluster. There are several flags available that can be added to the script.

Flag	Description	Default
--kubernetes-version	Version of kubernetes node components	optional, defaults to the version of vCluster k8s
--repository-url	Specific vCluster version to install	optional, defaults to /usr/local/bin
--binaries-dir	allows to customize target directory where k8s node components binaries are installed	optional, defaults to `/usr/local/bin
--cni-binaries-dir	allows to customize target directory where CNI binaries are installed	optional, defaults to /opt/cni/bin
--skip-reset	Skips uninstalling existing node components	optional, default to false (reset happens before install by default)
--bundle-path	If set, skips downloading Kubernetes binaries and uses a local path. Expects a path to bundle in .tar.gz format	optional, empty by default
--reset-only	only uninstall previously installed node components. Use this to cleanup the node	optional, defaults to false
--skip-join	Installs all required components but skips joining node to the cluster. This can be useful if you want to update the kubeadm join config before joining the node to the cluster manually by executing kubeadm join	optional, defaults to false
--node-name	Node name in the kubernetes cluster	optional, defaults to hostname
--force-join	Force joining even when there is existing kubelet service running on the node.	optional, defaults to false

These flags can be passed to the script by appending -- and then the flag:

Run join script with flags

curl -sfLk https://<vcluster-endpoint>/node/join?token=<token> | sh -s -- --force-join