Kubernetes Cluster Setup On Ubuntu: A Quick Guide

Nov 3, 2025 by Team 50 views

Setting up a Kubernetes (K8s) cluster on Ubuntu might sound intimidating, but trust me, it's totally doable. This guide will walk you through the process step-by-step, making it easy for anyone to get their own K8s environment up and running. Let's dive in!

Prerequisites

Before we get started, make sure you have the following:

Multiple Ubuntu Servers: You'll need at least two Ubuntu servers (1 master node and 1 worker node). Three or more nodes (1 master, 2+ workers) are recommended for a production environment, so you can simulate a more realistic setup.
Ubuntu Version: Use Ubuntu 20.04 or 22.04. These versions are well-tested and compatible with Kubernetes.
Root or Sudo Privileges: You need root or sudo privileges on all machines to install and configure the necessary software.
Internet Access: All servers need internet access to download packages.
Unique Hostnames and Static IPs: Assign unique hostnames and static IP addresses to each server. This helps in identifying and communicating between the nodes.

Step 1: Install Container Runtime (Docker)

First, let's install Docker, which Kubernetes uses to run containerized applications. Docker is the most common container runtime, and it's pretty straightforward to set up.

Update the package index: Open your terminal and run:
```
sudo apt update
```
Install required packages: Install packages that allow apt to use a repository over HTTPS:
```
sudo apt install apt-transport-https ca-certificates curl software-properties-common
```

Add Docker’s official GPG key: This ensures that the packages you’re installing are authentic:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Set up the stable Docker repository: Add the Docker repository to your system’s list of repositories:

echo "deb [arch=amd64 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

Install Docker Engine: Now, install Docker Engine, Docker CLI, and containerd:
```
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io
```
Verify Docker Installation: Check if Docker is installed correctly by running:
```
sudo docker run hello-world
```
If everything's working, you should see a "Hello from Docker!" message.
Enable Docker: Start Docker and enable it to start on boot:
```
sudo systemctl start docker
sudo systemctl enable docker
```

Step 2: Install Kubernetes Components (kubeadm, kubelet, kubectl)

Next up, we need to install the core Kubernetes components: kubeadm, kubelet, and kubectl. Let's break down what each one does:

kubeadm: A tool for bootstrapping Kubernetes clusters.
kubelet: An agent that runs on each node in the cluster to manage containers.
kubectl: A command-line tool for interacting with the Kubernetes cluster.

Here’s how to install them:

Add the Kubernetes apt repository: First, add the Kubernetes repository to your system:

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

Install kubeadm, kubelet, and kubectl: Now, install the necessary packages:
```
sudo apt update
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
```
The apt-mark hold command prevents these packages from being updated automatically, which can cause compatibility issues.

Step 3: Initialize the Kubernetes Cluster (Master Node)

Now that we've installed the necessary components, it's time to initialize the Kubernetes cluster on the master node. This step sets up the control plane.

Initialize the Kubernetes cluster: Use kubeadm to initialize the cluster. Replace <YOUR_MASTER_NODE_IP> with the actual IP address of your master node:
```
sudo kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=<YOUR_MASTER_NODE_IP>
```
Important: Make sure to note the kubeadm join command output at the end of this process. You'll need it to join worker nodes to the cluster.
Configure kubectl: To use kubectl, you need to configure it to connect to your cluster. Run the following commands as a regular user (not root):
```
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
```
Install a Pod Network Add-on: Kubernetes requires a pod network add-on to enable communication between pods. We'll use Calico, a popular and simple option. Apply the Calico manifest:
```
kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
```
Wait a few minutes for the pods to start running. You can check their status with:
```
kubectl get pods --all-namespaces
```

Step 4: Join Worker Nodes to the Cluster

With the master node set up, let’s add the worker nodes to the cluster. Remember that kubeadm join command from Step 3? You'll use it now.

Run the kubeadm join command: On each worker node, run the kubeadm join command that you saved earlier. It should look something like this:
```
sudo kubeadm join <YOUR_MASTER_NODE_IP>:6443 --token <TOKEN> --discovery-token-ca-cert-hash sha256:<HASH>
```
If you don't have the kubeadm join command, you can regenerate the token on the master node:
```
sudo kubeadm token create --print-join-command
```
Verify Node Status: Back on the master node, check the status of the worker nodes:
```
kubectl get nodes
```
You should see all your worker nodes listed with a status of Ready.

Step 5: Deploy a Sample Application

Now that your cluster is up and running, let's deploy a sample application to make sure everything is working correctly. We'll deploy a simple Nginx deployment.

Create a Deployment: Create an Nginx deployment using kubectl:
```
kubectl create deployment nginx --image=nginx
```

Expose the Deployment: Expose the deployment as a service:

kubectl expose deployment nginx --port=80 --type=NodePort

Check the Service: Get the service details and find the NodePort:
```
kubectl get service nginx
```
Look for the NodePort value (e.g., 30000).
Access the Application: Open your web browser and navigate to http://<WORKER_NODE_IP>:<NODE_PORT>. You should see the default Nginx welcome page.

Troubleshooting

Nodes Not Joining: Ensure that the master node's IP address is reachable from the worker nodes. Check firewall settings and network configurations.
Pods Not Starting: Check the pod logs using kubectl logs <pod-name> -n <namespace> to identify any errors. Ensure that the pod network is correctly configured.
kubectl Not Working: Verify that the ~/.kube/config file is correctly configured and that you have the necessary permissions.

Conclusion

And there you have it! You've successfully set up a Kubernetes cluster on Ubuntu. This is just the beginning, though. Kubernetes is a powerful platform with tons of features to explore, such as deployments, services, scaling, and more. Keep experimenting and happy clustering! Setting up a Kubernetes cluster using Ubuntu is a very common task, with Docker being the most common container runtime.