Kubernetes Installation and Cluster Setup

Your first production Kubernetes cluster will fail. Not because Kubernetes is broken, but because you skipped the boring parts: networking, storage, and security. I've seen teams spend weeks on YAML only to realize their cluster can't even pull images from a private registry. Kubernetes installation isn't just running a script—it's designing a control plane that survives a node failure, a network that doesn't drop packets, and a storage backend that doesn't corrupt data. This guide walks you through a production-grade setup using kubeadm, from prerequisites to cluster validation. No fluff, just the steps that matter.

Prerequisites and Environment Preparation

Before installing Kubernetes, your nodes must meet specific requirements. You need at least two machines (physical or virtual) running Ubuntu 22.04 LTS or CentOS 7/8. Each node should have a minimum of 2 CPU cores, 2 GB RAM, and 20 GB free disk space. All nodes must have unique hostnames, MAC addresses, and product_uuids. Disable swap: sudo swapoff -a and remove swap entries from /etc/fstab. Ensure the container runtime is installed—containerd is recommended over Docker. Install containerd from the official Docker repository. Configure the kernel modules overlay and br_netfilter: sudo modprobe overlay && sudo modprobe br_netfilter. Set sysctl params: net.bridge.bridge-nf-call-iptables = 1, net.ipv4.ip_forward = 1. Apply with sudo sysctl --system. These steps prevent common networking and resource issues during cluster initialization.

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

# Install containerd
sudo apt-get update
sudo apt-get install -y containerd
sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml
sudo systemctl restart containerd

# Kernel modules
sudo modprobe overlay
sudo modprobe br_netfilter

# Sysctl params
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system

Installing kubeadm, kubelet, and kubectl

With the environment ready, install the Kubernetes components. kubeadm initializes the cluster, kubelet runs on all nodes, and kubectl is the CLI. Add the Kubernetes repository and install specific versions to avoid compatibility issues. Use version 1.28.x as of this writing. Pin the versions to prevent accidental upgrades. On all nodes, run: sudo apt-get install -y kubelet=1.28.0-00 kubeadm=1.28.0-00 kubectl=1.28.0-00. Hold the packages: sudo apt-mark hold kubelet kubeadm kubectl. This ensures the cluster remains stable. After installation, enable and start kubelet: sudo systemctl enable --now kubelet. Verify with kubeadm version and kubectl version --client.

#!/bin/bash
# Add Kubernetes repository
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://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list

# Install specific version
sudo apt-get update
sudo apt-get install -y kubelet=1.28.0-00 kubeadm=1.28.0-00 kubectl=1.28.0-00
sudo apt-mark hold kubelet kubeadm kubectl

# Enable kubelet
sudo systemctl enable --now kubelet

Initializing the Control Plane with kubeadm

On the control plane node, initialize the cluster. kubeadm init sets up the control plane components: API server, controller manager, scheduler, and etcd. Choose a pod network CIDR that doesn't conflict with your existing network. Common choices: 10.244.0.0/16 for Flannel, 10.96.0.0/12 for services. Run: sudo kubeadm init --pod-network-cidr=10.244.0.0/16. This downloads images and starts containers. After success, you'll get a kubeconfig file and a join token. Copy the kubeconfig to your user directory: mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config. Verify with kubectl get nodes—the control plane node should show as NotReady until a network plugin is installed.

#!/bin/bash
# Initialize control plane
sudo kubeadm init --pod-network-cidr=10.244.0.0/16

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

# Check nodes
kubectl get nodes

Installing a Pod Network (CNI Plugin)

A Container Network Interface (CNI) plugin enables pod-to-pod communication. Without it, nodes remain NotReady and pods cannot communicate. Choose a CNI that fits your environment: Flannel (simple overlay), Calico (network policies), Weave (easy setup), or Cilium (eBPF). For this guide, install Flannel: kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml. After applying, check nodes: kubectl get nodes should show Ready. If nodes stay NotReady, check kubelet logs: journalctl -u kubelet -f. Common issues: wrong CIDR, firewall blocking ports 8472 (VXLAN), or missing kernel modules. Flannel uses VXLAN overlay; ensure UDP port 8472 is open between nodes.

#!/bin/bash
# Install Flannel CNI
kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

# Wait for nodes to become Ready
sleep 30
kubectl get nodes

Joining Worker Nodes to the Cluster

Worker nodes run your applications. To join them, use the token and hash from the kubeadm init output. If you lost it, generate a new token on the control plane: kubeadm token create --print-join-command. This prints the full join command. On each worker node, run the command with sudo: sudo kubeadm join <control-plane-ip>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>. After joining, verify on the control plane: kubectl get nodes. Worker nodes will show as NotReady initially, then become Ready after the CNI plugin is installed (if not already). Ensure the worker node has the same container runtime and Kubernetes version as the control plane. If join fails, check network connectivity to port 6443 and that the token hasn't expired (default 24 hours).

#!/bin/bash
# On worker node, run the join command from control plane
sudo kubeadm join 192.168.1.100:6443 --token abcdef.0123456789abcdef --discovery-token-ca-cert-hash sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

# On control plane, verify
kubectl get nodes

Configuring kubectl for Remote Access

By default, kubectl uses the admin.conf file on the control plane. To manage the cluster from your local machine, copy the kubeconfig file and update the server IP. On your local machine, install kubectl matching the cluster version. Copy the admin.conf from the control plane: scp user@control-plane:/etc/kubernetes/admin.conf ~/.kube/config. Edit the file to change the server address from localhost to the control plane's public IP or DNS. Test with kubectl cluster-info. For security, create a dedicated user with limited permissions instead of using admin.conf. Use RBAC to grant only necessary access. For example, create a read-only user for developers.

#!/bin/bash
# On local machine
scp user@192.168.1.100:/etc/kubernetes/admin.conf ~/.kube/config

# Update server IP
sed -i 's/127.0.0.1/192.168.1.100/g' ~/.kube/config

# Test
kubectl cluster-info

Deploying a Test Application

Verify the cluster works by deploying a simple application. Create a deployment: kubectl create deployment nginx --image=nginx:1.25. Expose it as a service: kubectl expose deployment nginx --port=80 --type=NodePort. Get the NodePort: kubectl get svc nginx. Access the application using any node's IP and the NodePort (e.g., http://192.168.1.101:30080). If it works, your cluster is functional. Check pod logs: kubectl logs deployment/nginx. If pods are pending, check node resources: kubectl describe node. Common issues: insufficient CPU/memory, image pull errors (check registry access), or network policy blocking.

#!/bin/bash
# Deploy nginx
kubectl create deployment nginx --image=nginx:1.25
kubectl expose deployment nginx --port=80 --type=NodePort

# Get service details
kubectl get svc nginx

# Access (replace with actual node IP)
curl http://192.168.1.101:$(kubectl get svc nginx -o jsonpath='{.spec.ports[0].nodePort}')

Setting Up Persistent Storage with HostPath

Stateful applications need persistent storage. For a simple setup, use HostPath volumes—they mount a directory from the node's filesystem into the pod. Create a PersistentVolume (PV) and PersistentVolumeClaim (PVC). Example PV: hostPath: path: /data. Then create a PVC that requests storage. Deploy a pod that uses the PVC. HostPath is not suitable for production because pods may be scheduled on different nodes. For production, use a network storage solution like NFS, Ceph, or cloud provider volumes. Test with a simple pod that writes to the volume and verify data persists after pod restart.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: hostpath-pv
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /data
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: hostpath-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Enabling the Kubernetes Dashboard

The Kubernetes Dashboard provides a web UI for cluster management. Install it with: kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml. Create a service account and cluster role binding for admin access. Then get a bearer token: kubectl -n kubernetes-dashboard create token admin-user. Start the proxy: kubectl proxy. Access the dashboard at http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/. Use the token to log in. The dashboard shows cluster resources, logs, and allows basic operations. For production, secure the dashboard with RBAC and HTTPS.

#!/bin/bash
# Install dashboard
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

# Create admin user
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: admin-user
  namespace: kubernetes-dashboard
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-user
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: admin-user
  namespace: kubernetes-dashboard
EOF

# Get token
kubectl -n kubernetes-dashboard create token admin-user

Cluster Backup and Restore with etcd

etcd stores all cluster state. Backing up etcd is critical for disaster recovery. Use etcdctl (v3) to take snapshots. On the control plane, run: ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key snapshot save /backup/etcd-snapshot.db. To restore, stop the API server and etcd, then restore the snapshot to a new data directory: ETCDCTL_API=3 etcdctl snapshot restore /backup/etcd-snapshot.db --data-dir=/var/lib/etcd-restore. Update the etcd manifest to use the new data directory. Test by starting the cluster and verifying resources.

#!/bin/bash
# Backup etcd
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /backup/etcd-snapshot-$(date +%Y%m%d).db

# Verify snapshot
ETCDCTL_API=3 etcdctl --write-out=table snapshot status /backup/etcd-snapshot-$(date +%Y%m%d).db

Troubleshooting Common Installation Issues

Even with careful setup, issues arise. Common problems: kubelet fails to start (check journalctl -u kubelet), nodes stay NotReady (CNI not installed or network issues), pods stuck in Pending (insufficient resources or PVC not bound), API server not responding (check firewall port 6443). Use kubectl describe to get details. For kubeadm init failures, check pre-flight checks: kubeadm init --dry-run. Ensure all nodes have synchronized clocks (install ntp). If images fail to pull, check container runtime and registry access. For network issues, verify CNI plugin logs: kubectl -n kube-system logs <cni-pod>. Keep a checklist and validate each step.

#!/bin/bash
# Check kubelet status
sudo systemctl status kubelet

# View kubelet logs
journalctl -u kubelet -n 50 --no-pager

# Check node details
kubectl describe node <node-name>

# Check pod events
kubectl describe pod <pod-name>

# Check CNI pods
kubectl -n kube-system get pods -l k8s-app=flannel

# Test API server
curl -k https://localhost:6443/healthz

Production Hardening and Next Steps

Your cluster is running, but it's not production-ready. Hardening steps: enable RBAC, use network policies, set resource limits, enable audit logging, and use a private container registry. Implement Pod Security Standards (baseline or restricted). Set up monitoring with Prometheus and Grafana. Configure logging with Fluentd or Loki. Use a service mesh like Istio for advanced traffic management. Automate deployments with CI/CD (GitLab CI, Jenkins). Finally, document your cluster architecture, backup procedures, and runbooks. Kubernetes is a platform, not a magic bullet—invest in operations.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: deny-all
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-dns
spec:
  podSelector: {}
  policyTypes:
  - Egress
  egress:
  - to:
    - namespaceSelector: {}
      podSelector:
        matchLabels:
          k8s-app: kube-dns
    ports:
    - port: 53
      protocol: UDP