Kubernetes Cluster on Ubuntu: A Step-by-Step Guide

Hey everyone! So, you’re looking to dive into the awesome world of Kubernetes and want to get a cluster up and running on your Ubuntu machines, huh? That’s a fantastic goal, guys! Building your own Kubernetes cluster is a super rewarding experience, and Ubuntu is a solid choice for hosting it. In this guide, we’re going to walk through the entire process, from setting up your nodes to getting your cluster operational. We’ll break it down into easy-to-follow steps, so even if you’re relatively new to Kubernetes, you’ll be able to get there. Think of this as your ultimate roadmap to Kubernetes mastery on Ubuntu. We’ll cover the prerequisites, essential tools, and the actual commands you’ll need to type. So, grab your favorite beverage, settle in, and let’s get this cluster built!

Why Ubuntu for Your Kubernetes Cluster?

Alright, let’s chat for a sec about why Ubuntu is such a popular and solid choice for running your Kubernetes cluster. When you’re setting up something as powerful and complex as Kubernetes, you want an operating system that’s stable, well-supported, and plays nice with all the necessary components. Ubuntu Server ticks all those boxes and then some. For starters, its long-term support (LTS) releases mean you get a stable foundation that’s maintained for years, which is crucial for production environments or even just for your learning projects so you don’t have to constantly upgrade. It also has a massive community behind it. If you ever run into a snag – and let’s be honest, with complex tech like Kubernetes, you probably will – there’s a high chance someone else has already faced it and there’s a solution or guide out there. This means fewer headaches and more time actually using your cluster.

Furthermore, Ubuntu has excellent package management with apt . Installing and updating software, including all the components needed for Kubernetes like containerd or docker , kubeadm , kubelet , and kubectl , is generally straightforward. This simplifies the setup and maintenance significantly. Security is also a big plus. Ubuntu has a strong focus on security features and regular updates, which is vital when you’re running a system that will orchestrate your applications. Plus, it’s resource-efficient . Compared to some other enterprise-grade OSs, Ubuntu Server can be quite lean, meaning more of your server’s power is available for your actual Kubernetes workloads, not just the OS itself. And let’s not forget the sheer compatibility . Most cloud providers and hardware vendors officially support Ubuntu, making it a familiar and well-trodden path for developers and sysadmins alike. So, when you combine all these factors – stability, community support, ease of use, security, efficiency, and compatibility – Ubuntu emerges as a champion choice for building and running your Kubernetes cluster. It provides a robust and user-friendly environment that lets you focus on learning and leveraging the power of Kubernetes without getting bogged down by OS-level complexities. Seriously, you can’t go wrong picking Ubuntu for this mission!

Prerequisites: What You’ll Need Before You Start

Before we jump into the nitty-gritty of installing Kubernetes on Ubuntu, let’s make sure you’ve got all your ducks in a row. Having these prerequisites sorted beforehand will save you a ton of time and potential frustration down the line. Think of this as your pre-flight checklist, guys!

First off, you’ll need at least two Ubuntu machines . One will act as your control plane node (the brain of your cluster), and the other(s) will be your worker nodes (where your applications will actually run). For testing and learning, two machines are the minimum. For anything more serious, you’ll want multiple worker nodes. These machines should be running a compatible version of Ubuntu . While Kubernetes is pretty flexible, sticking to recent LTS (Long-Term Support) versions like Ubuntu 20.04 LTS or 22.04 LTS is highly recommended for stability and support. Make sure they are fully updated with sudo apt update && sudo apt upgrade -y .

Next up, network connectivity is absolutely critical. All your nodes need to be able to communicate with each other without any firewalls blocking the necessary ports. Ensure your machines are on the same network or have a clear path to communicate. You’ll need SSH access to all your nodes with a user that has sudo privileges. This is how we’ll be running all the commands. Unique hostnames for each node are also a must. Each machine should have a distinct name that the others can resolve. You can check and set this using the hostnamectl command.

Crucially, you need to disable swap on all nodes. Kubernetes doesn’t play well with swap memory. You can disable it temporarily with sudo swapoff -a and then permanently by commenting out the swap line in /etc/fstab . It’s also a good idea to configure unique MAC addresses and product/UUIDs for your machines if you’re running them in a virtual environment, especially if you’re cloning nodes. Kubernetes uses these for identification. Finally, ensure you have curl and gnupg installed on all nodes, as we’ll use them to add repositories and download necessary packages. You can install them with sudo apt install -y curl gnupg . Having these basics covered means we’re ready to get our hands dirty with the actual Kubernetes setup. Let’s move on!

Installing Container Runtime (containerd)

Alright, team, the first major step in setting up our Kubernetes cluster on Ubuntu is installing a container runtime . Kubernetes itself doesn’t run containers directly; it delegates that job to a container runtime installed on each node. While Docker was the historical choice, containerd is now the preferred and recommended runtime for Kubernetes. It’s more lightweight and has a simpler architecture. So, let’s get containerd installed and configured on all our nodes – that includes the control plane and all worker nodes.

First things first, let’s ensure our system is ready to go. We need to make sure some kernel modules are loaded and some system configurations are in place to allow Kubernetes networking to function properly. On each node, run the following commands:

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

sudo modprobe overlay
sudo modprobe br_netfilter

# sysctl params required by setup, params usually be found in /etc/sysctl.d/kubernetes.conf
cat <<EOF | sudo tee /etc/sysctl.d/kubernetes.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
fs.inotify.max_user_watches = 89584
EOF

# Apply sysctl params without reboot
sudo sysctl --system

These commands ensure that the necessary kernel modules ( overlay and br_netfilter ) are loaded, and networking parameters are set for Kubernetes to manage network traffic correctly. The fs.inotify.max_user_watches setting is often needed by certain tools and libraries that Kubernetes relies on.

Now, let’s install containerd . We’ll add the official Kubernetes repository to ensure we get a version compatible with Kubernetes. Run these commands on each node :

# Add Docker's official GPG key: (containerd is part of Docker ecosystem)
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources:
echo 
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu 
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | 
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install containerd.io
sudo apt-get update
sudo apt-get install -y containerd.io

After installing containerd , we need to configure it. Kubernetes expects containerd to use a specific configuration that enables the systemd cgroup driver, which is generally recommended for better integration with system services.

Run this command to generate the default containerd configuration file:

sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

Now, we need to edit this configuration file to ensure the SystemdCgroup option is set to true . Use your favorite text editor (like nano or vim ) to open the file:

sudo nano /etc/containerd/config.toml

Find the [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options] section and make sure it looks like this:

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
  # the}^{+}$,
  BinaryName = "/usr/bin/runc"
  # ... other settings ...

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
  SystemdCgroup = true 

Note: If you don’t see SystemdCgroup , you might need to add it under the [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options] section. Save and exit the editor.

Finally, restart the containerd service to apply the changes:

sudo systemctl restart containerd

And enable it to start on boot:

sudo systemctl enable containerd

Boom! You’ve successfully installed and configured containerd on all your nodes. This is a huge step and gets us ready for the next phase: installing Kubernetes itself.

Installing Kubernetes Components (kubeadm, kubelet, kubectl)

Alright, now that our container runtime is humming along nicely, it’s time to install the core Kubernetes components: kubeadm , kubelet , and kubectl . These are the tools that will help us bootstrap, manage, and interact with our cluster. We need to install these on all nodes – the control plane and the worker nodes alike.

First, let’s prepare our system by disabling the swap space, which Kubernetes requires. If you haven’t done this already during the prerequisites, do it now on all nodes:

# Disable swap immediately
sudo swapoff -a

# Persist this change by commenting out swap entries in /etc/fstab
# Use your favorite editor, e.g., sudo nano /etc/fstab
# Find the line that looks like /swapfile none swap sw 0 0 and comment it out by adding a '#' at the beginning.

Next, we’ll add the official Kubernetes package repository to our Ubuntu system. This ensures we get the latest stable versions. Run the following commands on each node :

”`bash

Update package list and install prerequisite packages

sudo apt-get update sudo apt-get install -y apt-transport-https ca-certificates curl gpg

Download the Google Cloud public signing key

curl -fsSL https://dl.k8s.io/key/secrets-inline.pub | sudo gpg –dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

The above command is deprecated, use the new one:

curl -fsSL