Joining a Node in a Kubernetes cluster

This guide outlines the steps to join a nodes to a cluster.

Requires one of the following licenses:

CM: Standard, Professional, Enterprise
DCM: Standard, Professional, Enterprise

Tags:

5 minute read

To increase performance or add additional resource capacity to your cluster, adding a node to the cluster is the correct process. This process with kubeopsctl is very easy.
You can use the following steps to join control-plane nodes or worker-nodes to a Kubernetes cluster.

Join Node Process:

Prerequisites

Recommended: Log in with KOSI

Before performing any action with KubeOps Container Manager, it is recommended to log in with kosi. For more information, see the official KOSI documentation here.

Recommended: Create an ETCD backup

Before making changes to the control-plane nodes, it is recommended to create an ETCD backup. For more information, see the official Kubernetes documentation here

Example 1: Join a Control-Plane Node to a Kubernetes Cluster

1. Pull the required KOSI packages on your ADMIN

If you do not specify a parameter, the current Kubernetes version 1.32.2 will be pulled.
To pull a specific Kubernetes version, use the --kubernetesVersion x.xx.x parameter.
Available Kubernetes versions are

kubeopsctl pull

2. Add the node definition to cluster-values.yaml

Note To join a node to your cluster, changeCluster must be set to true.

Add the new control-plane node definition to the appropriate zone in cluster-values.yaml:

  - name: demo-controlplaneXX
    iPAddress: 10.2.10.XXX
    type: controlplane
    kubeVersion: 1.31.6

Note The kubeVersion parameter defines the Kubernetes version for the node. It must be set to the same version that is already running in your cluster.

3. Update your cluster-values.yaml in zone1

Update your cluster-values.yaml based on the example below. Make sure that:

kubernetesVersion is set to the current cluster version.
kubeVersion for the new node matches the version already used in the cluster.
The new node is added to the correct zone.

The following example shows the configuration for zone1.

Note Pay close attention to the format and syntax in the cluster-values.yaml

# file cluster-values.yaml
apiVersion: kubeops/kubeopsctl/cluster/beta/v1
imagePullRegistry: registry.kubeops.net/kubeops/kubeops
airgap: false
clusterName: myCluster
clusterUser: root
kubernetesVersion: 1.31.6       # -> current cluster version
kubeVipEnabled: false           
virtualIP: 10.2.10.110
firewall: nftables
pluginNetwork: calico
containerRuntime: containerd
kubeOpsRoot: /home/myuser/kubeops
serviceSubnet: 192.168.128.0/17
podSubnet: 192.168.0.0/17
debug: true
systemCpu: 250m
systemMemory: 256Mi
packageRepository: https://packagerepo.kubeops.net/
changeCluster: true             # -> must be set
zones:
- name: zone1
  nodes:
  - name: demo-controlplane01
    iPAddress: 10.2.10.110
    type: controlplane
    kubeVersion: 1.31.6       
  - name: demo-controlplaneXX   # -> replace with the new node name
    iPAddress: 10.2.10.XXX      # -> replace with the new node IP
    type: controlplane
    kubeVersion: 1.31.6         # -> must match the current cluster version
  - name: demo-worker01
    iPAddress: 10.2.10.210
    type: worker
    kubeVersion: 1.31.6       
- name: zone2
  nodes:
  - name: demo-controlplane02
    iPAddress: 10.2.10.120
    type: controlplane
    kubeVersion: 1.31.6       
  - name: demo-worker02
    iPAddress: 10.2.10.220
    type: worker
    kubeVersion: 1.31.6       
- name: zone3
  nodes:
  - name: demo-controlplane03
    iPAddress: 10.2.10.130
    type: controlplane
    kubeVersion: 1.31.6      
  - name: demo-worker03
    iPAddress: 10.2.10.230
    type: worker
    kubeVersion: 1.31.6

4. Validate the configuration and join the node After updating cluster-values.yaml, review the file again to confirm that all values are correct.

Then start the join process:

kubeopsctl apply -f cluster-values.yaml

Example 2: Join a Worker Node to a Kubernetes Cluster

1. Pull the required KOSI packages on your ADMIN

If you do not specify a parameter, the current Kubernetes version 1.32.2 will be pulled.

To pull a different Kubernetes version, use the –kubernetesVersion x.xx.x parameter.

Available Kubernetes versions are

kubeopsctl pull

2. Add the node definition in the cluster-values.yaml

Note To join a node to your cluster, changeCluster must be set to true.

Add the new worker node definition to the appropriate zone in cluster-values.yaml:

  - name: demo-workerXX
    iPAddress: 10.2.10.XX
    type: worker
    kubeVersion: 1.31.6

Note TThe kubeVersion parameter defines the Kubernetes version for the node. It must be set to the same version that is already running in your cluster.

3. Adjust your cluster-values in zone2
Adjust your cluster-values in comparison to the example below. Be sure to set the actual version in your values, as well as the target version in the nodes. In the snippet below it is just the zone2.

kubernetesVersion is set to the current cluster version.
kubeVersion for the new node matches the version already used in the cluster.
The new node is added to the correct zone.

The following example shows the configuration for zone2.

Note Pay close attention to the format and syntax in cluster-values.yaml.

# file cluster-values.yaml
apiVersion: kubeops/kubeopsctl/cluster/beta/v1
imagePullRegistry: registry.kubeops.net/kubeops/kubeops
airgap: false
clusterName: myCluster
clusterUser: root
kubernetesVersion: 1.31.6        # -> current cluster version
kubeVipEnabled: false           
virtualIP: 10.2.10.110
firewall: nftables
pluginNetwork: calico
containerRuntime: containerd
kubeOpsRoot: /home/myuser/kubeops
serviceSubnet: 192.168.128.0/17
podSubnet: 192.168.0.0/17
debug: true
systemCpu: 250m
systemMemory: 256Mi
packageRepository: https://packagerepo.kubeops.net/
changeCluster: true              # -> must be set
zones:
- name: zone1
  nodes:
  - name: demo-controlplane01
    iPAddress: 10.2.10.110
    type: controlplane
    kubeVersion: 1.31.6       
  - name: demo-worker01
    iPAddress: 10.2.10.210
    type: worker
    kubeVersion: 1.31.6       
- name: zone2
  nodes:
  - name: demo-controlplane02
    iPAddress: 10.2.10.120
    type: controlplane
    kubeVersion: 1.31.6       
  - name: demo-worker02
    iPAddress: 10.2.10.220
    type: worker
    kubeVersion: 1.31.6       
  - name: demo-workerXX          # -> replace with the new node name
    iPAddress: 10.2.10.XX        # - replace with the new node IP
    type: worker
    kubeVersion: 1.31.6          # -> must match the current cluster version    
- name: zone3
  nodes:
  - name: demo-controlplane03
    iPAddress: 10.2.10.130
    type: controlplane
    kubeVersion: 1.31.6      
  - name: demo-worker03
    iPAddress: 10.2.10.230
    type: worker
    kubeVersion: 1.31.6

3. Validate your values and join the node to the cluster

Once the cluster-values.yaml is created, check the values once again. Before joining the node, note the following:

Note

It is recommended if you join worker nodes to a cluster and rook-ceph is installed, to adjust your rook-ceph CRUSH map. Refer to the official rook-ceph documentation for details here. for updating the crush map, you should set in your enterprise-values.yaml:

...
packages:
- name: rook-ceph
  enabled: true
...

If you are ready, start the join node process with the command:

kubeopsctl apply -f cluster-values.yaml

If you need to apply the CRUSH map adjustment from above, use the following command instead:

kubeopsctl apply -f cluster-values.yaml -f enterprise-values.yaml