Join Manually Provisioned Nodes
Prerequisites​
- vClustervClusterAn open-source software product that creates and manages tenant clusters within Kubernetes infrastructure. vCluster provides tenant isolation capabilities while reducing infrastructure costs. CLI installed on your local machine
- vCluster 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. has to be running and in
Readystate - A node that satisfies the node requirements
Create token​
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.
- Control-Plane As Container
- Control-Plane As Binary
Make sure your kube context is set to vCluster Standalone.
# Create a token
vcluster token create --expires=1h
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:
curl -sfLk https://<vcluster-endpoint>/node/join?token=<token> | sh -
Join each worker node​
For each worker node that you want to join vCluster, run the command on the 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.
Join with a node profile​
If 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. is connected to vCluster Platform, you can attach a node profile to a node as part of the join. This saves you from joining the node bare and configuring it by hand afterward.
- Open the tenant cluster instance in the platform UI and click Attach Node Directly.
- Optionally select a profile from the list of profiles allowed in the project. If you don't select one, the node falls back to the tenant cluster's or project's default profile, when configured.
- Copy the returned curl command and run it on the target node, as described in Join each worker node. Changing the selected profile regenerates the command.
The node joins carrying the profile's labels and taints, plus a vcluster.com/node-profile=<name> back-reference label. From then on, the platform continuously reconciles the profile onto the node, so later edits to the profile converge automatically without rejoining the node. See Assignment and precedence for how the fallback chain resolves.
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 k8sK8sThe standard Kubernetes distribution that can be used in tenant clusters, offering full compatibility with upstream Kubernetes features. |
--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:
curl -sfLk https://<vcluster-endpoint>/node/join?token=<token> | sh -s -- --force-join