How To Change A Kubernetes Node Name

Changing a node name in Kubernetes is generally not recommended as it can cause issues with the cluster and its workloads. Since Kubernetes environments are meant to be mostly ephemeral, there should be very little danger in fully replacing a node instead of trying to change a node name in place.

How to change a Kubernetes Node Name

If you really need to change the name of a node, you can do so by following these steps. Please note that the steps listed do not actually change a node name, they fully replace a node in your cluster.

Drain the node

Before you can change the node name, you need to make sure that there are no workloads running on the node. You can do this by "draining" the node, which will evict all of the running pods from the node. You can use the following command to drain the node:

$ kubectl drain {node-name}

Replace {node-name} with the name of the node you want to drain. This command will gracefully terminate all of the running pods on the node and prevent new pods from being scheduled on the node.

Delete the node

Once the node is drained, you can delete the node using the following command:

$ kubectl delete node {node-name}

Replace {node-name} with the name of the node you want to delete. This command will remove the node from the cluster.

Delete and replace the worker node

Depending on your environment, it is recommend that you fully delete a node and replace it instead of changing its name. You can modify /etc/hostname and your /etc/hosts file to change the node to a new name, but I would highly recommend that you go ahead and fully replace it. You will end up with fewer unexpected issues in the future.

Be sure to follow any of your original setup steps to get a node ready to be bootstrapped.

Add the node back to the cluster

First, you need to install a Kubernetes node on the machine that you want to add to the cluster. You can do this by following the installation instructions for your chosen Kubernetes distribution.

Once you have installed the node, you need to generate a join command that will allow the node to join the cluster. You can do this on the control plane node (i.e., the node where the kubelet service is running) by running the following command:

$ kubeadm token create --print-join-command

This will output a join command that you can use to add the node to the cluster.

Run the join command on the new node: Copy the join command from the output of the previous command and run it on the new node as root. For example:

$ sudo kubeadm join {control-plane-node}:{port} --token {token} --discovery-token-ca-cert-hash sha256:{hash}

Replace {control-plane-node} with the IP address or hostname of the control plane node, {port} with the port number used by the control plane node's API server (typically 6443), {token} with the token generated by the kubeadm token create command, and {hash} with the hash of the CA certificate used by the control plane node.

Note that you may need to run this command with additional flags depending on your cluster configuration.

Verify that the node has joined the cluster: Once you have run the join command on the new node, you can verify that the node has joined the cluster by running the following command on the control plane node:

$ kubectl get nodes

This command will output a list of all of the nodes in the cluster, including the new node.

$ kubectl get nodes
NAME            STATUS   ROLES    AGE     VERSION
node-1          Ready    &lt;none>   12d     v1.22.4
node-2          Ready    &lt;none>   7d      v1.22.4
node-3          Ready    &lt;none>   5d      v1.22.4

Conclusion

Note that changing the name of a node can have implications for your cluster and its workloads, especially if you have services that depend on the node name. It's generally recommended to avoid changing node names unless it's absolutely necessary, and to test any changes in a non-production environment first.

How To Change A Kubernetes Node Name

Related Articles