Kubernetes On Ubuntu: A Step-by-Step Installation Guide

Nov 3, 2025 by Team 56 views

Alright, guys! Let's dive into the world of Kubernetes and get it up and running on Ubuntu. This guide is designed to be super easy to follow, even if you're relatively new to container orchestration. We'll walk through each step, ensuring you understand what's happening and why. By the end of this article, you'll have a fully functional Kubernetes cluster humming away on your Ubuntu machines. So, buckle up, and let's get started!

Prerequisites

Before we jump into the installation, let's make sure we have all the necessary tools and configurations in place. This section is crucial, so don't skip it! Think of it as gathering your ingredients before starting a recipe. Missing something here can lead to frustrating errors later on.

Ubuntu Servers: You'll need at least one Ubuntu server to act as your master node and optionally, one or more worker nodes. I recommend using Ubuntu 20.04 or later. Ensure these servers have network connectivity and can communicate with each other. A good starting point is to have at least 2GB of RAM and 2 vCPUs for each server.
Container Runtime: Kubernetes needs a container runtime to run containers. Docker is a popular choice, but we'll be using containerd in this guide, as it's becoming increasingly favored in the Kubernetes ecosystem. Don't worry; we'll walk through the containerd installation process.
Internet Access: Your servers will need internet access to download packages and dependencies. Make sure your network configuration allows outbound connections.
User Privileges: You'll need sudo privileges on all the servers to install and configure Kubernetes components.
Basic Linux Knowledge: A basic understanding of Linux commands and concepts will be helpful. You should be comfortable navigating the command line, editing files, and managing services.

Detailed Look at Prerequisites

Having the right prerequisites in place is like laying a solid foundation for a building. Without it, things can get shaky and unstable pretty quickly. Let's delve deeper into why each of these prerequisites is important.

First, Ubuntu Servers form the backbone of your Kubernetes cluster. The master node is the brain of the operation, responsible for managing and coordinating all the worker nodes. Worker nodes are where your actual applications will run. The choice of Ubuntu is strategic – it's a widely supported and well-documented Linux distribution, making it easier to troubleshoot issues and find community support. Using the latest LTS (Long Term Support) version, like Ubuntu 20.04 or later, ensures you're getting the latest security patches and features. When sizing your servers, remember that Kubernetes can be resource-intensive, so having enough RAM and CPU is crucial for performance.

Next, the Container Runtime, in our case containerd, is the engine that actually runs your containers. It's the component that takes the container images and turns them into running applications. Containerd is lightweight and efficient, making it a great choice for Kubernetes. It's also a Cloud Native Computing Foundation (CNCF) project, which means it's actively maintained and supported by the Kubernetes community. While Docker is another viable option, containerd is increasingly becoming the standard due to its tighter integration with Kubernetes.

Internet Access is essential because Kubernetes relies on downloading various packages and dependencies from online repositories. Without it, you won't be able to install the necessary components. Ensure your servers can reach the internet and that any firewalls or network policies aren't blocking the required traffic. This is a common gotcha, so double-check your network configuration if you run into issues.

User Privileges are required because installing and configuring Kubernetes involves making system-level changes. You'll need sudo access to install packages, modify system files, and start/stop services. Make sure the user you're using has the necessary permissions.

Finally, Basic Linux Knowledge is incredibly helpful. While this guide aims to be as detailed as possible, a familiarity with Linux commands and concepts will make the process smoother. You should be comfortable navigating the command line, editing files with tools like nano or vim, and managing services with systemctl. This knowledge will also be invaluable when troubleshooting issues and customizing your Kubernetes cluster.

Installing containerd

Okay, let's get our hands dirty and install containerd, our chosen container runtime. Containerd is a CNCF graduated project, emphasizing its reliability and integration within the Kubernetes ecosystem. It's a lightweight runtime that efficiently manages container execution. Here’s how to install it on Ubuntu:

Update Package Index:
```
sudo apt update
```
This command updates the list of available packages and their versions.
Install Dependencies:
```
sudo apt install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common
```
These packages are required to add and use the Docker’s official GPG key and repository.
Add Docker GPG Key:
```
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
```
This command adds the official Docker GPG key to your system, allowing you to verify the authenticity of the packages you'll be downloading from the Docker repository.
Add Docker Repository:
```
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
```
This command adds the Docker repository to your system's list of software sources. This allows you to install containerd and other Docker-related packages using apt.
Install containerd:
```
sudo apt install -y containerd.io
```
This command installs the containerd.io package, which includes the containerd runtime and its associated utilities.
Configure containerd:
```
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
```
This creates the /etc/containerd directory and generates a default configuration file for containerd. The tee command ensures that the output of containerd config default is both displayed in the terminal and saved to the /etc/containerd/config.toml file.
Edit containerd Configuration:
```
sudo nano /etc/containerd/config.toml
```
Open the configuration file in a text editor (like nano). Find the SystemdCgroup = false line and change it to SystemdCgroup = true. This ensures that containerd uses the systemd cgroup driver, which is required for Kubernetes.
Restart containerd:
```
sudo systemctl restart containerd
```
This command restarts the containerd service to apply the new configuration changes.
Enable containerd:
```
sudo systemctl enable containerd
```
This command ensures that containerd starts automatically on boot.

Why these steps are important for containerd

Let's break down why each of these steps is essential for a successful containerd installation. Understanding the rationale behind each command will not only help you troubleshoot issues but also give you a deeper understanding of how containerd works.

The first few steps, involving updating the package index and installing dependencies, are standard practice when installing software on Ubuntu. They ensure that you have the latest information about available packages and that you have all the necessary tools to proceed with the installation. The apt-transport-https, ca-certificates, curl, gnupg-agent, and software-properties-common packages are crucial for securely adding and using external repositories like the Docker repository.

Adding the Docker GPG key and repository is necessary because containerd is distributed through the Docker ecosystem. The GPG key allows you to verify that the packages you're downloading are authentic and haven't been tampered with. The Docker repository provides access to the containerd.io package, which contains the containerd runtime.

The containerd config default command generates a default configuration file for containerd. This file contains various settings that control how containerd operates. The tee command is used to both display the output of the command and save it to a file, making it easy to review and modify the configuration.

Editing the containerd configuration file to set SystemdCgroup = true is a crucial step for Kubernetes integration. Kubernetes relies on the systemd cgroup driver for managing container resources. Without this setting, Kubernetes may not be able to properly allocate resources to your containers, leading to performance issues and instability. This is a very common issue when installing Kubernetes, so make sure not to skip this step.

Finally, restarting and enabling the containerd service ensures that the new configuration changes are applied and that containerd starts automatically on boot. This is essential for ensuring that your Kubernetes cluster remains operational after a reboot.

Installing Kubernetes Components

Now that containerd is set up, let's install the core Kubernetes components: kubeadm, kubelet, and kubectl. These tools are the building blocks of your Kubernetes cluster.

kubeadm: A tool for bootstrapping Kubernetes clusters.
kubelet: An agent that runs on each node in the cluster and ensures that containers are running as expected.
kubectl: A command-line tool for interacting with the Kubernetes API server.

Here’s how to install them:

Add Kubernetes Apt Repository:
```
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
sudo apt-add-repository "deb http://apt.kubernetes.io/ kubernetes-xenial main"
```
These commands add the Kubernetes apt repository to your system. The first command imports the Google Cloud Platform public key, which is used to verify the authenticity of the Kubernetes packages. The second command adds the Kubernetes repository to your system's list of software sources.
Update Package Index:
```
sudo apt update
```
This updates the list of available packages and their versions, including the ones from the newly added Kubernetes repository.
Install Kubernetes Components:
```
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
```
This installs the kubelet, kubeadm, and kubectl packages. The apt-mark hold command prevents these packages from being automatically updated, which can cause compatibility issues.

Deep Dive into Kubernetes Components Installation

Let's understand each step involved in installing the Kubernetes components – kubelet, kubeadm, and kubectl. This knowledge will help you appreciate their roles and troubleshoot any potential issues.

Adding the Kubernetes apt repository is essential because it provides access to the official Kubernetes packages. The first command, which imports the Google Cloud Platform public key, ensures that you're downloading packages from a trusted source. This is a critical security measure that prevents malicious actors from distributing compromised software.

The second command, which adds the Kubernetes repository to your system's list of software sources, tells your system where to find the Kubernetes packages. This allows you to install kubelet, kubeadm, and kubectl using the apt package manager.

Updating the package index after adding the Kubernetes repository is crucial because it ensures that your system has the latest information about the available Kubernetes packages. Without this step, you may not be able to install the correct versions of the Kubernetes components.

Installing kubelet, kubeadm, and kubectl is the core of this process. kubeadm is a command-line tool that simplifies the process of bootstrapping a Kubernetes cluster. It automates many of the steps involved in setting up a cluster, such as generating certificates and configuring the control plane. kubelet is an agent that runs on each node in the cluster and ensures that containers are running as expected. It communicates with the Kubernetes control plane to receive instructions and report the status of the containers running on the node. kubectl is a command-line tool that allows you to interact with the Kubernetes API server. You can use it to deploy applications, manage resources, and monitor the health of your cluster.

The apt-mark hold command is used to prevent the kubelet, kubeadm, and kubectl packages from being automatically updated. This is important because Kubernetes upgrades can sometimes introduce compatibility issues. By holding these packages, you can ensure that your cluster remains stable and that you have time to test any upgrades before applying them.

Initializing the Kubernetes Cluster

With the Kubernetes components installed, we can now initialize the cluster. This step sets up the control plane and prepares the cluster for running workloads.

Initialize the Kubernetes Cluster:
```
sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --container-runtime=containerd
```
This command initializes the Kubernetes control plane. The --pod-network-cidr flag specifies the IP address range that will be used for pods in the cluster. The --container-runtime flag specifies the container runtime to use, which in our case is containerd. Important: Save the kubeadm join command that is outputted at the end of this process. You will need it to add worker nodes to the cluster.
Configure kubectl:
```
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
```
These commands configure kubectl to connect to the Kubernetes API server. They copy the Kubernetes configuration file from /etc/kubernetes/admin.conf to $HOME/.kube/config and set the correct ownership and permissions.
Install a Pod Network Add-on:
```
kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
```
This installs the Flannel pod network add-on, which provides networking between pods in the cluster. Other options include Calico, Weave Net, and Cilium. Make sure the network add-on is compatible with the --pod-network-cidr you chose during kubeadm init.

Breaking Down the Cluster Initialization

Let's dissect the Kubernetes cluster initialization process to understand what's happening under the hood. This will help you troubleshoot issues and customize your cluster to meet your specific needs.

The kubeadm init command is the cornerstone of this process. It performs a series of tasks to set up the Kubernetes control plane, including:

Generating certificates for secure communication between the Kubernetes components.
Creating the necessary Kubernetes API objects, such as pods, services, and deployments.
Configuring the kube-apiserver, kube-scheduler, and kube-controller-manager components.
Setting up the etcd distributed key-value store, which is used to store the Kubernetes cluster state.

The --pod-network-cidr flag specifies the IP address range that will be used for pods in the cluster. This range must be unique and not overlap with any other networks in your environment. Choosing the right pod network CIDR is important for ensuring that pods can communicate with each other and with external services.

The --container-runtime flag specifies the container runtime to use, which in our case is containerd. This flag tells kubeadm which container runtime to configure for use with Kubernetes.

After running kubeadm init, it is very important to save the kubeadm join command, which is outputted at the end of the process. This command contains the necessary information to add worker nodes to the cluster. You will need to run this command on each worker node to join it to the control plane.

The next set of commands configures kubectl to connect to the Kubernetes API server. These commands copy the Kubernetes configuration file from /etc/kubernetes/admin.conf to $HOME/.kube/config and set the correct ownership and permissions. This allows you to use kubectl to interact with the Kubernetes cluster from your user account.

Installing a pod network add-on is essential for providing networking between pods in the cluster. The pod network add-on is responsible for assigning IP addresses to pods and routing traffic between them. Flannel is a popular choice for a pod network add-on, but other options are available. Make sure to choose a pod network add-on that is compatible with your environment and meets your specific needs.

Joining Worker Nodes

To add worker nodes to the cluster, you'll use the kubeadm join command that was outputted during the initialization process. Run this command on each worker node:

kubeadm join <control-plane-ip>:<control-plane-port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>

Replace <control-plane-ip>, <control-plane-port>, <token>, and <hash> with the values from the kubeadm join command that you saved earlier.

Understanding the Join Command

The kubeadm join command is the key to expanding your Kubernetes cluster with worker nodes. Let's break down its components to understand how it works.

The <control-plane-ip> and <control-plane-port> specify the IP address and port of the Kubernetes control plane. This allows the worker node to connect to the control plane and register itself as a member of the cluster.

The --token flag provides a security token that is used to authenticate the worker node with the control plane. This token is generated during the kubeadm init process and is unique to each cluster. It prevents unauthorized nodes from joining the cluster.

The --discovery-token-ca-cert-hash flag provides a hash of the control plane's certificate authority (CA) certificate. This allows the worker node to verify the authenticity of the control plane and prevent man-in-the-middle attacks. The CA certificate is used to sign the certificates of the Kubernetes components, and the hash ensures that the worker node is connecting to a genuine control plane.

When you run the kubeadm join command on a worker node, it performs the following tasks:

Downloads the necessary Kubernetes components, such as kubelet and kube-proxy.
Configures kubelet to connect to the Kubernetes API server.
Registers the worker node with the Kubernetes control plane.
Starts the kubelet service, which begins running containers on the node.

Verifying the Installation

Finally, let's verify that our Kubernetes cluster is up and running correctly. On the master node, run the following command:

kubectl get nodes

This command will display a list of all the nodes in the cluster, along with their status. You should see your master node and any worker nodes that you have joined. If the status of all the nodes is Ready, then congratulations! You have successfully installed Kubernetes on Ubuntu.

You can also check the status of the Kubernetes components by running the following command:

kubectl get pods --all-namespaces

This command will display a list of all the pods in the cluster, along with their status. You should see the Kubernetes system pods running in the kube-system namespace. If all the pods are running and healthy, then your Kubernetes cluster is functioning correctly.

Conclusion

Congratulations! You've successfully installed Kubernetes on Ubuntu. This guide walked you through the process step by step, from installing the necessary prerequisites to verifying the installation. You now have a fully functional Kubernetes cluster that you can use to deploy and manage your applications. Remember to explore the Kubernetes documentation and experiment with different features to learn more about this powerful container orchestration platform. Happy deploying!