Skip to content
Search

Kubeadm

lastmod 2025-12-18created 2024-06-1223 edits

Kubeadm is a tool built to provide kubeadm init and kubeadm join as best-practice "fast paths" for creating Kubernetes clusters.

kubeadm performs the actions necessary to get a minimum viable cluster up and running. By design, it cares only about bootstrapping, not about provisioning machines. Likewise, installing various nice-to-have addons, like the Kubernetes Dashboard, monitoring solutions, and cloud-specific addons, is not in scope.

Instead, we expect higher-level and more tailored tooling to be built on top of kubeadm, and ideally, using kubeadm as the basis of all deployments will make it easier to create conformant clusters.

Installing kubeadm

This page shows how to install the kubeadm toolbox. For details on how to create a cluster with kubeadm after performing this installation process, see #Creating a cluster with kubeadm.

Before you begin

  • A compatible Linux host. The Kubernetes project provides generic instructions for Linux distributions based on Debian and Red Hat, and for distributions without a package manager.
  • 2 GB or more of RAM per machine (any less leaves little room for your apps).
  • 2 CPUs or more for control plane machines.
  • Full network connectivity between all machines in the cluster (public or private network is fine).
  • Unique hostname, MAC address, and product_uuid for every node. See #Verify the MAC address and product_uuid are unique for every node for details.
  • Certain ports must be open on your machines. See #Check required ports for details.

WARNING

The kubeadm installation is done via binaries that use dynamic linking and assumes that your target system provides glibc. This is a reasonable assumption on many Linux distributions (including Debian, Ubuntu, Fedora, CentOS, etc.) but it is not always the case with custom and lightweight distributions which don't include glibc by default, such as Alpine Linux. The expectation is that the distribution either includes glibc or a compatibility layer that provides the expected symbols.

Check your OS version

Kubernetes clusters created by kubeadm depend on software that uses kernel features. This software includes, but is not limited to, the container runtime, the kubelet, and Container Network Interface plugins.

To help you avoid unexpected errors as a result of an unsupported kernel version, kubeadm runs the SystemVerification pre-flight check. This check fails if the kernel version is not supported.

You may choose to skip the check if you know that your kernel provides the required features, even though kubeadm does not support its version.

Verify the MAC address and product_uuid are unique for every node

  • You can get the MAC address of the network interfaces using the command ip link or ifconfig -a
  • You can check the product_uuid using the command sudo cat /sys/class/dmi/id/product_uuid

It is very likely that hardware devices will have unique addresses, although some virtual machines may have identical values. Kubernetes uses these values to uniquely identify the nodes in the cluster. If these values are not unique to each node, the installation process may fail.

Check network adapters

If you have more than one network adapter, and your Kubernetes components are not reachable on the default route, we recommend you add IP route(s) so Kubernetes cluster addresses go via the appropriate adapter.

Check required ports

These required ports need to be open in order for Kubernetes components to communicate with each other. You can use tools like netcat to check if a port is open.

For example: 

nc 127.0.0.1 6443 -zv -w 2

The pod network plugin you use may also require certain ports to be open. Since this differs with each pod network plugin, refer to the plugin's documentation about what port(s) it needs.

See #iptables rules below.

Swap configuration

The default behavior of a kubelet is to fail to start if swap memory is detected on a node. This means that swap should either be disabled or tolerated by kubelet.

  • To tolerate swap, add failSwapOn: false to the kubelet configuration or set it as a command-line argument. Note: even if failSwapOn: false is provided, workloads wouldn't have swap access by default. This can be changed by setting a swapBehavior, again in the kubelet configuration file. To use swap, set a swapBehavior other than the default NoSwap setting. See swap memory management for details.
  • To disable swap, sudo swapoff -a can be used to disable swapping temporarily. To make this change persistent across reboots, make sure swap is disabled in config files like /etc/fstab, systemd.swap, depending on how it was configured on your system.

Installing a container runtime

To run containers in Pods, Kubernetes uses a container runtime.

By default, Kubernetes uses the Container Runtime Interface (CRI) to interface with your chosen container runtime.

If you don't specify a runtime, kubeadm automatically tries to detect an installed container runtime by scanning through a list of well-known endpoints.

If multiple or no container runtimes are detected, kubeadm will return an error and will request that you specify which one you want to use.

See container runtimes for more information.

The tables below include the known endpoints for supported operating systems.

Linux:

Runtime

Path to Unix domain socket

containerd

unix:///var/run/containerd/containerd.sock

CRI-O

unix:///var/run/crio/crio.sock

Docker Engine (using cri-dockerd)

unix:///var/run/cri-dockerd.sock

Windows:

Runtime

Path to Windows named pipe

containerd

npipe:////./pipe/containerd-containerd

Docker Engine (using cri-dockerd)

npipe:////./pipe/cri-dockerd

Installing kubeadm, kubelet and kubectl

You will install these packages on all of your machines.

  • kubeadm - the command to bootstrap the cluster.
  • kubelet - the component that runs on all of the machines in your cluster and does things like starting pods and containers.
  • kubectl - the command-line utility to talk to your cluster.

kubeadm will not install or manage kubelet or kubectl for you, so you will need to ensure they match the version of the Kubernetes control plane you want kubeadm to install for you. If you do not, there is a risk of a version skew occurring that can lead to unexpected, buggy behaviour. However, one minor version skew between the kubelet and the control plane is supported, but the kubelet version may never exceed the API server version. For example, a kubelet running 1.7.0 should be fully compatible with a 1.8.0 API server, but not vice versa.

For information about installing kubectl, see Install and set up kubectl.

Configuring a cgroup driver

Both the container runtime and the kubelet have a property called "cgroup driver", which is important for the management of cgroups on Linux machines.

Matching the cgroup drivers of the container runtime and the kubelet is required, or otherwise the kubelet process will fail.

See Configuring a cgroup driver for more details.

Commands

  • kubeadm init - initialize the master node
  • kubeadm join - initialize a worker node and join it to the cluster
  • kubeadm token - check tokens

Loading kernel modules

To load them after reboot: 

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

Then load each one: 

sudo modprobe overlay
sudo modprobe br_netfilter

Check that they loaded properly: 

lsmod | grep overlay
lsmod | grep br_netfilter

For details on each, see the following:

iptables rules 

# Kubernetes Control plane
-A INPUT -p tcp --dport 6443      -j ACCEPT -m comment --comment "Kubernetes API server"
-A INPUT -p tcp --dport 2379:2380 -j ACCEPT -m comment --comment "etcd server client API"
-A INPUT -p tcp --dport 10250     -j ACCEPT -m comment --comment "Kubelet API"
-A INPUT -p tcp --dport 10259     -j ACCEPT -m comment --comment "kube-scheduler"
-A INPUT -p tcp --dport 10257     -j ACCEPT -m comment --comment "kube-controller-manager"

# Kubernetes Worker node(s)
-A INPUT -p tcp --dport 10250       -j ACCEPT -m comment --comment "Kubelet API"
-A INPUT -p tcp --dport 10256       -j ACCEPT -m comment --comment "kube-proxy"
-A INPUT -p tcp --dport 30000:32767 -j ACCEPT -m comment --comment "NodePort Services"
-A INPUT -p udp --dport 30000:32767 -j ACCEPT -m comment --comment "NodePort Services"

# FORWARD 체인 설정 (컨테이너 간 통신)
-A FORWARD -j ACCEPT

Allow bridge traffic (required for Kubernetes)

Add sysctl settings.

Setting it in roughly a /etc/sysctl.d/80-kubernetes.conf file should do? In practice, go into the directory, check, and then edit. 

net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1

For an explanation of each item, see the separate pages:

After adding the file, apply it right away with the sudo sysctl --system command.

Creating a cluster with kubeadm

Installing on WSL

Explanations of each step are omitted. Only the key points are summarized below.

Add WSL settings at C:\Users\<username>\.wslconfig: 

[wsl2]
swap=0

Restart with wsl --shutdown.

Troubleshooting

=== kubelet : Depends: kubernetes-cni (>= 1.2.0) but it is not installable === 

The following packages have unmet dependencies:
 kubelet : Depends: kubernetes-cni (>= 1.2.0) but it is not installable
E: Unable to correct problems, you have held broken packages.
root@ubuntu-jammy:/home/vagrant#

See also

Favorite site

author Zer0 sitemap