如何将Ubuntu物理机配置为Kubernetes节点并加入现有集群

Hey there! I totally get how frustrating it is when you're just starting out with Kubernetes and can't find clear, up-to-date steps for adding a regular physical Ubuntu machine to an existing cluster. Most guides either skip key steps, are outdated, or focus solely on cloud instances. Let's fix that—here's a detailed, beginner-friendly walkthrough.

Prerequisites First #

Before we dive in, make sure you have these covered:

• Your existing Kubernetes control plane node can communicate with this Ubuntu physical machine (check network connectivity, ensure port 6443 is open between them).
• The Ubuntu machine meets Kubernetes' minimum requirements: at least 2 CPU cores, 2GB of RAM, and 20GB of free disk space (more is better for real workloads).
• Use a stable Ubuntu LTS version (20.04 or 22.04 are recommended—avoid non-LTS releases for consistency).

Step 1: Prepare the Ubuntu Physical Machine #

These steps need to be run directly on the Ubuntu machine you want to add as a node.

Disable Swap #

Kubernetes requires swap to be disabled (it can interfere with pod scheduling).

• Turn off swap temporarily:

  sudo swapoff -a
  

• Disable swap permanently (so it stays off after reboot):

  sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
  

Configure Kernel Parameters #

We need to set up kernel modules and network settings required by Kubernetes.

• Load necessary modules:

  sudo modprobe overlay
  sudo modprobe br_netfilter
  

• Create a sysctl configuration file for Kubernetes:

  sudo tee /etc/sysctl.d/k8s.conf <<EOF
  net.bridge.bridge-nf-call-iptables  = 1
  net.bridge.bridge-nf-call-ip6tables = 1
  net.ipv4.ip_forward                 = 1
  EOF
  

• Apply the new sysctl settings:

  sudo sysctl --system
  

Install a Container Runtime (Containerd) #

Kubernetes needs a container runtime to run pods. Containerd is the official recommended runtime now.

• Install prerequisite packages:

  sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
  

• Add Docker's GPG key (used to sign containerd packages):

  curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
  

• Add the containerd repository to your apt sources:

  echo \
    "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
    $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  

• Install containerd:

  sudo apt update && sudo apt install -y containerd.io
  

• Configure containerd to use systemd cgroups (matches Ubuntu's init system):
  • Generate the default config file:

    sudo containerd config default | sudo tee /etc/containerd/config.toml
    

  • Edit the config file to set SystemdCgroup to true:
    Open /etc/containerd/config.toml with your preferred editor (like nano: sudo nano /etc/containerd/config.toml), find the section [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options], and change SystemdCgroup = false to SystemdCgroup = true.
  • Restart containerd to apply changes:

    sudo systemctl restart containerd
    

Install Kubeadm, Kubelet, and Kubectl #

These are the core Kubernetes tools needed to join the cluster.

• Add Kubernetes' GPG key:

  curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-archive-keyring.gpg
  

• Add the Kubernetes repository to apt:

  echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
  

• Install the same version as your existing control plane node (critical for compatibility—replace 1.28.0-00 with your cluster's version):

  sudo apt update && sudo apt install -y kubelet=1.28.0-00 kubeadm=1.28.0-00 kubectl=1.28.0-00
  

• Lock the versions to prevent accidental updates (which can break compatibility):

  sudo apt-mark hold kubelet kubeadm kubectl
  

• Enable and start the kubelet service:

  sudo systemctl enable --now kubelet
  

Step 2: Join the Ubuntu Machine to Your Existing Cluster #

Now we'll connect the node to your cluster using the control plane's join command.

Get the Join Command from the Control Plane #

Log into your existing Kubernetes control plane node, then run:

kubeadm token create --print-join-command

This will output a command that looks like this:

kubeadm join 192.168.1.100:6443 --token abcdef.0123456789abcdef --discovery-token-ca-cert-hash sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Copy this entire command—it's what you'll run on the Ubuntu physical machine.

Run the Join Command on the Ubuntu Machine #

Paste the copied command into the Ubuntu machine's terminal, prefixing it with sudo:

sudo kubeadm join 192.168.1.100:6443 --token abcdef.0123456789abcdef --discovery-token-ca-cert-hash sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Wait for the process to complete—you should see a success message when it's done.

Step 3: Verify the Node is Added #

Back on your control plane node, run this command to list all cluster nodes:

kubectl get nodes

You should see your new Ubuntu node listed with a status of Ready. If it shows NotReady at first, wait a minute or two—kubelet might still be setting things up. If it stays NotReady, check the kubelet logs for errors:

sudo journalctl -u kubelet -f

Quick Troubleshooting Tips #

• Token expired? If the join command fails because the token is invalid, regenerate it on the control plane with kubeadm token create --print-join-command.
• Version mismatch? Double-check that kubeadm/kubelet versions on the new node match the control plane—this is a common source of issues.
• Network issues? Ensure the physical machine can ping the control plane's IP, and that port 6443 isn't blocked by a firewall.

内容的提问来源于stack exchange，提问作者Kamil