Running Kubernetes on Linux: A Complete Beginner's Guide

Introduction / Why This Matters

Kubernetes has become the industry standard for container orchestration. Understanding its architecture and learning how to manage a cluster opens a direct path to DevOps engineering and modern CI/CD practices. In this guide, you will deploy a fully functional local cluster on Linux, get acquainted with the kubectl utility, and launch your first application. After completing this guide, you will be able to safely experiment with Deployments, Services, and scaling without impacting production environments.

Prerequisites / Preparation

Before you begin, ensure your system meets the following minimum requirements:

• A Debian- or Ubuntu-based Linux distribution (22.04/24.04)
• At least 2 GB of RAM and 2 CPU cores
• 20 GB of free disk space
• A stable internet connection
• sudo privileges or direct root access

Step 1: Update the System and Disable Swap

Kubernetes does not support operation with an active swap file. First, update your package lists and install essential utilities:

sudo apt update && sudo apt install -y curl apt-transport-https

Disable swap for the current session and comment out the corresponding line in /etc/fstab to ensure the change persists across reboots:

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

💡 Tip: When using virtual machines, allocate at least 4 GB of RAM to the guest OS. This prevents etcd crashes and ensures stable API server performance.

Step 2: Install and Configure containerd

Modern Kubernetes versions rely on CRI-compliant container runtimes. We will install containerd and prepare its configuration:

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

Enable the systemd cgroup driver. This is the recommended approach for resource management and guarantees proper integration with the Kubernetes scheduler:

sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl enable containerd

Step 3: Deploy the Local Cluster

Minikube provides a fast, isolated environment that is ideal for learning. Download the latest binary and make it executable:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Initialize the cluster, explicitly specifying the resources and startup driver:

minikube start --driver=none --cpus=2 --memory=2048

The initialization process will take 2–4 minutes. A successful completion is indicated by the message kubectl configured to use "minikube" cluster and "default" namespace.

Step 4: Configure kubectl and Verify Status

Minikube automatically configures the kubectl context. Verify that kubectl can communicate with the cluster and that the node has reached a ready state:

kubectl cluster-info
kubectl get nodes

The output should display a node named minikube with a Ready status. If the status differs, wait another minute or check the component logs using journalctl -u kubelet.

Step 5: Deploy a Test Application

Create a Deployment running an Nginx web server and expose it via a NodePort Service:

kubectl create deployment nginx-test --image=nginx:stable
kubectl expose deployment nginx-test --type=NodePort --port=80

Retrieve the external URL to access the application directly:

minikube service nginx-test --url

Open the generated link in your browser or run curl <URL> in your terminal. You should see the default Nginx welcome page.

Verifying the Results

Confirm that all components are functioning correctly by running a comprehensive diagnostic check:

kubectl get pods,svc,deployments
kubectl get events --sort-by='.lastTimestamp'

A healthy cluster will show a Running status for the Pod, NodePort for the Service, and no critical events in the latest log entries. Try scaling the Deployment with kubectl scale deployment nginx-test --replicas=3 and observe how the orchestrator automatically provisions new containers.

Troubleshooting

• ErrImagePull or ImagePullBackOff error: Verify your internet connection and the image name. If you are using a private registry, configure imagePullSecrets or run minikube image pull <image> before deploying.
• Node in NotReady status: This is usually caused by a network driver issue or swap remaining active. Run sudo cat /proc/swaps. If swap files are listed, disable them again and restart kubelet using sudo systemctl restart kubelet.
• Ports in use: Minikube requires free ports 8443, 10250, and several others. Use ss -tulnp | grep -E '8443|10250' to identify conflicts, stop the interfering service, and retry the startup.