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

Nov 3, 2025 by Team 51 views

Hey everyone! 👋 Ever wanted to dive into the world of container orchestration? If so, installing a Kubernetes cluster on Ubuntu is a fantastic place to start. Kubernetes, often called K8s, is like the brain of your containerized applications, making sure they run smoothly, scale up or down as needed, and are always available. This guide will walk you through the process, making it super easy to get your own Kubernetes cluster up and running on Ubuntu. Whether you're a newbie or have some experience, this step-by-step tutorial is designed to help you succeed. Let's get started and see how to install Kubernetes cluster on Ubuntu!

Prerequisites: What You'll Need

Before we jump in, let's make sure you've got everything you need. You'll need a few things to follow along with this Kubernetes installation on Ubuntu guide:

Ubuntu Server: You'll need at least one Ubuntu Server instance. I recommend using the latest LTS (Long Term Support) version to ensure you get the latest features and security updates. This guide is specifically for Ubuntu, but the general concepts apply to other Linux distributions as well.
Sudo Access: Ensure you have sudo privileges on your Ubuntu server. This is super important because you'll need it to install and configure various packages.
Internet Connection: Your server will need an active internet connection to download all the necessary packages and dependencies. Kubernetes itself and its related tools can be quite a download, so make sure your connection is stable.
Basic Understanding of Linux: A basic understanding of Linux commands and concepts will be helpful. Knowing how to navigate the command line, edit files, and run commands is essential. Don't worry if you're not an expert; you'll learn as you go!
Recommended Hardware: While Kubernetes can run on modest hardware, more resources will lead to better performance. For a basic cluster, I'd recommend at least 2GB of RAM and 2 CPUs per node. For production environments, you'll need more resources. Also, you'll want at least two Ubuntu server instances to create a proper cluster. You will designate one as the master node and the other as the worker node.

Okay, cool! With these prerequisites in place, we're ready to start building our Kubernetes cluster. This setup is perfect for learning and experimenting with Kubernetes. As you get more comfortable, you can scale it up and add more nodes.

Step 1: Update Your Ubuntu Server

First things first, we need to make sure our Ubuntu server is up-to-date. This step is crucial because it ensures that you have the latest security patches and software updates. It will also prevent any compatibility issues during the installation. Open your terminal and run the following commands:

sudo apt update
sudo apt upgrade -y

The apt update command refreshes the package index, and apt upgrade -y upgrades all installed packages to their latest versions. The -y flag automatically answers 'yes' to any prompts, so the process is faster and doesn't require any interaction.

Once the update and upgrade are complete, it's a good idea to reboot your server to ensure that all changes take effect. You can do this with the following command:

sudo reboot

After your server reboots, log back in and proceed to the next step. Keeping your system updated is a fundamental practice in server administration, and it sets a solid foundation for your Kubernetes cluster installation.

Step 2: Disable Swap Memory

Kubernetes has some specific requirements, and one of them is that swap memory should be disabled on all nodes. Swap memory, if you don't know, is like virtual RAM that uses disk space when your system's RAM is full. Kubernetes can behave unpredictably with swap enabled, so disabling it is a must. Run this command to disable swap:

sudo swapoff -a

To make this change permanent, you need to edit the /etc/fstab file. This file contains information about file systems and how they should be mounted during boot. You'll need to comment out any lines that start with /swap. Use a text editor like nano or vim to edit the file:

sudo nano /etc/fstab

Find any lines that contain the word swap and add a # at the beginning of the line to comment it out. For example:

#/swap.img none swap sw 0 0

Save the file and exit the editor. Now, the swap will be disabled on the next reboot. This step is critical for Kubernetes to function correctly and avoid any performance issues. Keep this in mind during the whole Kubernetes cluster installation on Ubuntu process.

Step 3: Install Docker

Kubernetes uses containers to manage applications, and Docker is the most popular container platform. You need to install Docker on each node of your cluster. Here's how to do it:

Install Docker:

First, update the apt package index:
```
sudo apt update
```
Then, install Docker using the following command:
```
sudo apt install docker.io -y
```
Verify Docker Installation:

After the installation, check if Docker is running and its version:
```
sudo docker version
```
This command should display detailed Docker information, indicating that the installation was successful.
Enable Docker on Boot:

To ensure that Docker starts automatically when your server boots, use the following command:
```
sudo systemctl enable docker
```
Add Your User to the Docker Group:

This step is optional but highly recommended. Adding your user to the docker group allows you to run Docker commands without needing sudo. However, you can skip this if you like, and run sudo docker instead.
```
sudo usermod -aG docker $USER
```
After running this command, you'll need to log out and log back in, or run newgrp docker for the changes to take effect. If you are using SSH, then you will have to exit the terminal and reconnect to the server.

Docker is now set up on your Ubuntu server. It's the engine that will run your containerized applications within your Kubernetes cluster. This step is absolutely crucial for the whole Kubernetes on Ubuntu setup.

Step 4: Install Kubernetes Components

Now, let's get into the heart of the matter and install the Kubernetes components. We'll use kubeadm, kubelet, and kubectl:

Add Kubernetes Repository:

First, add the Kubernetes repository to your system's package sources. This will allow you to install the latest versions of Kubernetes components easily. Run these commands:
```
sudo apt-get update
```

sudo apt-get install -y apt-transport-https ca-certificates curl sudo curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://packages.cloud.google.com/apt/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list sudo apt-get update ```

These commands add the GPG key and the Kubernetes repository, ensuring that you can securely download and install the Kubernetes packages.

Install Kubernetes Packages:

Now, install the essential Kubernetes packages. This includes kubeadm, kubelet, and kubectl:
```
sudo apt-get install -y kubelet kubeadm kubectl
```
These packages are the core components you need to manage your Kubernetes cluster.
Hold Kubernetes Packages:

To prevent accidental upgrades of the Kubernetes packages, hold them. This ensures that the packages won't be updated automatically with apt upgrade. You can do this with the following command:
```
sudo apt-mark hold kubelet kubeadm kubectl
```
Holding the packages is a good practice to maintain control over your Kubernetes version and prevent unexpected issues. Also, this way ensures you install Kubernetes cluster on Ubuntu safely.

Step 5: Initialize the Kubernetes Master Node

Now, it's time to initialize your Kubernetes master node. This step sets up the control plane, which manages your cluster. This is only done on your master node.

Initialize the Master Node:

Run the following command on your master node to initialize the cluster:
```
sudo kubeadm init --pod-network-cidr=10.244.0.0/16
```
Replace 10.244.0.0/16 with a CIDR block of your choice for the pod network. This command might take a few minutes. If you encounter any issues during this process, make sure to check the command and troubleshoot.
Set Up kubectl:

After initialization, you need to configure kubectl to connect to your cluster. This involves creating a ~/.kube/config file, which contains the configuration details. The output of the kubeadm init command will provide you with the necessary commands to set up kubectl.

You will be instructed to run the following commands as a regular user, these commands setup 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 will set up your `kubectl` configuration, and you can now start managing your cluster through the command-line interface. Be sure to perform these steps on both the master and worker nodes, so you can interact with the cluster from each.

Install a Pod Network:

After initializing the master node, you need to install a pod network add-on. This enables communication between pods. There are several options available, such as Calico, Flannel, and Weave Net. I recommend using Flannel, which is relatively easy to set up. You can install it using the following command. The command can be found on the Kubernetes official website after initialization.
```
kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
```
This command deploys Flannel to your cluster. It might take a few minutes for the pods to become ready. To verify, run kubectl get pods -A. You should see that the pods are in the Running state.

With these steps, your master node is fully set up, and you're ready to add worker nodes to the cluster. This is an important step to install Kubernetes cluster on Ubuntu.

Step 6: Join Worker Nodes to the Cluster

Now, let's add worker nodes to your cluster. This is how you can scale your application across multiple nodes. You must do this after you initialize the master node. On each of your worker nodes, you need to run the kubeadm join command. This is why you need to set up the Kubernetes on Ubuntu setup first before joining the worker nodes to the cluster.

Get the Join Command:

Run the following command on your master node to retrieve the kubeadm join command that you'll use to join worker nodes to your cluster:
```
kubeadm token create --print-join-command
```
This command generates a token and prints the kubeadm join command. Copy this command.
Join the Worker Nodes:

On each worker node, run the kubeadm join command that you copied from the master node. The command should look something like this:
```
sudo kubeadm join <master-ip>:<master-port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>
```
Replace <master-ip> and <master-port> with the IP address and port of your master node, <token> with the token, and <hash> with the CA certificate hash. The values are generated by the master node and should be placed into the worker nodes during the join process.

Run this command on each of your worker nodes. The command will join the worker nodes to the cluster.
Verify Node Status:

On your master node, run the following command to verify that the worker nodes have joined the cluster:
```
kubectl get nodes
```
You should see the names of your worker nodes in the output. The status of the nodes should be Ready. If the status is not Ready, it might take a few minutes for the nodes to become ready. If they're not ready after a while, there might be a problem with the networking or node configuration.

With these steps, you have successfully set up a basic Kubernetes cluster with a master node and worker nodes. You can now start deploying your applications to the cluster. Congrats, you successfully install Kubernetes cluster on Ubuntu!

Step 7: Testing Your Kubernetes Cluster

Now that you've got your Kubernetes cluster up and running, let's do a quick test to make sure everything's working as it should. This is important to ensure that the whole Kubernetes on Ubuntu setup is successful.

Deploy a Sample Application:

Let's deploy a simple test application, such as the nginx web server, to your cluster. You can do this with the following command:
```
kubectl create deployment nginx --image=nginx:latest
```
This command creates a deployment that runs the nginx container. It pulls the image from Docker Hub and starts the containers.
Expose the Deployment:

Next, expose the deployment to make it accessible from outside the cluster. You can expose it using the following command:
```
kubectl expose deployment nginx --port=80 --type=LoadBalancer
```
This command creates a service that exposes the nginx deployment on port 80. The --type=LoadBalancer option makes the service accessible from outside the cluster. In a real environment, it's best to use a more appropriate service type, such as NodePort or Ingress.
Get the External IP:

To access the nginx web server, you need to find the external IP address of the service. You can get this with the following command:
```
kubectl get service nginx
```
Look for the EXTERNAL-IP address in the output. If it shows <pending>, it means the LoadBalancer hasn't been assigned an external IP yet. Wait a few moments and run the command again. If you're running this in a local environment, you can use the node's IP address and port 30000. If you do not have an external IP, you should get the service running at a NodePort
Access the Application:

Open a web browser and go to the external IP address (or the node's IP address and port 30000) that you found in the previous step. You should see the default nginx welcome page, which indicates that your deployment and service are working correctly. If you've been following along, congrats on a successful install Kubernetes cluster on Ubuntu!

Troubleshooting Common Issues

Setting up a Kubernetes cluster can sometimes be a bit tricky, but don't worry, everyone faces challenges. Here are a few common issues and their solutions when you install Kubernetes cluster on Ubuntu:

Connection Refused: Make sure your firewall isn't blocking the traffic to your cluster. Kubernetes uses several ports, so ensure that you've opened the necessary ones. Also, confirm the network configuration.
Pod Stuck in Pending State: Check your pod's logs with kubectl logs <pod-name> -n <namespace>. Common issues include image pull errors, resource limits, and networking issues. Make sure your images are accessible, and the networking is set up correctly.
Nodes Not Ready: If your nodes are not in the Ready state, check the logs of the kubelet service on each node with sudo journalctl -u kubelet. Look for any error messages that indicate a problem. Also, make sure that the system time is synchronized across all nodes. Kubernetes is highly sensitive to time discrepancies.
Docker Issues: Ensure that Docker is running correctly on each node and that it has enough resources. Check your Docker daemon logs to diagnose issues. Also, verify that the container runtime is configured correctly and that the CRI (Container Runtime Interface) is functioning well.
Networking Problems: If your pods can't communicate with each other, it's likely a networking problem. Double-check your pod network configuration (e.g., Flannel, Calico), and make sure that the network policies are set up correctly. Confirm that the pod network CIDR does not conflict with any other networks in your environment.

Conclusion

There you have it! You've successfully installed a Kubernetes cluster on Ubuntu. We've covered the essential steps, from prerequisites to testing. Kubernetes is a powerful tool for managing containerized applications, and now you have the knowledge to get started. Continue experimenting with it, and remember to always read the documentation. Have fun and enjoy the world of Kubernetes!

This guide should provide you with a solid foundation for setting up and managing your own Kubernetes cluster on Ubuntu. Remember to practice, learn, and have fun. Happy containerizing! If you want to learn more, just search on the internet! There are tons of resources available!