Create Kubernetes Cluster On Ubuntu: A Quick Guide

Oct 23, 2025 by Jhon Lennon 51 views

Setting up a Kubernetes cluster on Ubuntu might seem daunting at first, but trust me, it's totally achievable with the right steps. In this guide, we'll walk you through the process, making it as straightforward as possible. Whether you're a developer looking to containerize your applications or a sysadmin aiming to orchestrate deployments, understanding how to create a Kubernetes cluster is a valuable skill. So, let's dive in and get your cluster up and running!

Prerequisites

Before we get started, let's make sure you have everything you need. First off, you'll want at least two Ubuntu servers – one will act as the master node, and the other(s) will be worker nodes. Ensure these servers have network connectivity between them. You should also have sudo privileges on all machines. It's also good practice to update your Ubuntu packages to the latest versions. Run the following commands on each server:

sudo apt update
sudo apt upgrade -y

Next, you'll need to ensure that containerd is installed as the container runtime. Kubernetes has deprecated Docker as a supported runtime, so containerd is the way to go. We'll walk through the installation process for containerd in the next section. Also, make sure that kubeadm, kubelet, and kubectl are installed. These are the essential tools for bootstrapping and managing your Kubernetes cluster. We'll cover their installation as well. Finally, it's crucial to disable swap memory on all nodes. Kubernetes requires this for proper functioning. You can disable swap with the following command:

sudo swapoff -a

To make this change permanent, you'll need to comment out the swap entry in your /etc/fstab file. Open the file with sudo nano /etc/fstab and add a # at the beginning of the line that contains /swap.img or /swapfile. Save the file and exit. Rebooting the servers after these changes is a good idea to ensure everything is applied correctly. Remember, consistency is key when setting up a Kubernetes cluster. Each node needs to be configured in the same way to avoid unexpected issues down the line.

Installing containerd

Alright, let’s get containerd installed. This is a crucial step because Kubernetes uses containerd to manage containers. First, we need to configure the containerd repository. Add the Kubernetes apt repository by running:

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
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

Next, update the package list and install containerd:

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

Now, let’s configure containerd. Create the default configuration file:

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

Open the /etc/containerd/config.toml file using sudo nano /etc/containerd/config.toml. Find the [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc] section and change SystemdCgroup = false to SystemdCgroup = true. This ensures that containerd uses systemd for managing cgroups, which is a requirement for Kubernetes. Save the file and exit.

Restart containerd to apply the changes:

sudo systemctl restart containerd

Finally, verify that containerd is running correctly:

sudo systemctl status containerd

If everything is set up correctly, you should see that the service is active and running. This confirms that containerd is ready to be used by Kubernetes. Remember to perform these steps on all your nodes, including the master and worker nodes. Consistency is key to a successful Kubernetes cluster setup. Keep an eye on any error messages during the installation process and address them promptly to avoid complications later on.

Installing kubeadm, kubelet, and kubectl

With containerd up and running, our next step is to install kubeadm, kubelet, and kubectl. These tools are essential for managing your Kubernetes cluster. kubeadm helps you bootstrap the cluster, kubelet is the agent that runs on each node, and kubectl is the command-line tool you use to interact with the cluster. To begin, add the Kubernetes apt repository:

curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list

Update the package list and install the required packages:

sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl

Hold the package versions to prevent accidental upgrades, which could lead to compatibility issues:

sudo apt-mark hold kubelet kubeadm kubectl

kubelet will likely be in a failed state at this point because it's trying to connect to the Kubernetes API server, which we haven't set up yet. Don't worry, this is normal. We'll initialize the cluster in the next section. These steps need to be performed on all nodes, just like the containerd installation. Make sure each node has the same versions of kubeadm, kubelet, and kubectl to ensure consistency across the cluster. Keeping these tools at the same version helps prevent unexpected behavior and makes troubleshooting easier. Once you've installed these tools on all nodes, you're ready to initialize the master node and join the worker nodes to the cluster.

Initializing the Kubernetes Master Node

Now that we've installed all the necessary components, it's time to initialize the Kubernetes master node. This is a critical step that sets up the control plane for your cluster. On your designated master node, run the following command:

sudo kubeadm init --pod-network-cidr=10.244.0.0/16

The --pod-network-cidr flag specifies the IP address range for pods in your cluster. 10.244.0.0/16 is a common choice, but you can use a different range if needed. Make sure this range doesn't conflict with any existing networks in your environment. After running the kubeadm init command, you'll see a lot of output. Pay close attention to the last few lines, as they contain important instructions for configuring kubectl and joining worker nodes to the cluster. You'll see something like this:

  kubeadm join <your_master_ip>:<port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>

Copy this command and save it somewhere, as you'll need it later when joining the worker nodes. First, let's configure kubectl to work with your new cluster. Run the following commands as a regular user (not root):

mkdir -p $HOME/.kube
sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

These commands copy the Kubernetes configuration file to your home directory and set the correct permissions, allowing you to use kubectl without sudo. Next, you need to install a pod network add-on. This allows pods to communicate with each other. We'll use Calico in this example. Run the following command:

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

This command applies the Calico manifest, which sets up the pod network. It may take a few minutes for the pods to start running. You can check the status of the pods with the following command:

kubectl get pods -n kube-system

Wait until all the Calico pods are in the Running state before proceeding. This ensures that the pod network is properly configured. Once the Calico pods are running, your master node is fully initialized and ready to accept worker nodes.

Joining Worker Nodes to the Cluster

With the master node initialized, it's time to join the worker nodes to the cluster. On each worker node, run the kubeadm join command that you saved earlier. It should look something like this:

sudo kubeadm join <your_master_ip>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

Replace <your_master_ip>, <token>, and <hash> with the values provided by the kubeadm init command on the master node. If you've lost the kubeadm join command, you can regenerate it on the master node by running the following commands:

sudo kubeadm token create --print-join-command

This will generate a new kubeadm join command that you can use to join worker nodes. After running the kubeadm join command on each worker node, the nodes will start the joining process. This may take a few minutes. You can check the status of the nodes on the master node by running the following command:

kubectl get nodes

You should see all your worker nodes listed, with a status of Ready. If a node is not showing up as Ready, check the kubelet logs on that node for any errors. You can view the logs with the following command:

sudo journalctl -u kubelet

Look for any error messages that might indicate a problem with the joining process. Common issues include network connectivity problems, incorrect token values, or misconfigured kubelet settings. Once all your worker nodes are showing up as Ready, your Kubernetes cluster is successfully set up! You can now deploy applications to your cluster and start experimenting with Kubernetes features. Congratulations on creating your Kubernetes cluster on Ubuntu! Now go forth and orchestrate!