Kubernetes Installation Guide

Kubernetes (K8s) is an open-source container orchestration platform. This comprehensive guide covers multiple installation methods across Windows 11, macOS, and Linux.

Trademark Notice

Kubernetes® and the Kubernetes logo are registered trademarks of The Linux Foundation. K8s® is a registered trademark of The Linux Foundation. All trademarks and logos are used for representation purposes only. No prior copyright or trademark authorization has been obtained. This documentation is for educational purposes only.

Installation Options

Tool	Best For	Complexity	Production Ready
Minikube	Local development, learning	Low	No
kind	CI/CD, testing	Low	No
Docker Desktop	Simple local setup	Very Low	No
k3s	Lightweight, edge, IoT	Medium	Yes
kubeadm	Full cluster setup	High	Yes
Managed Services	Production workloads	Low	Yes

---

Prerequisites

• Docker installed (Installation Guide)
• kubectl command-line tool
• Minimum 2 CPUs and 4GB RAM
• Internet connection for downloading images

---

Installing kubectl

kubectl is the Kubernetes command-line tool required for all installations.

Windows 11

# Using Chocolatey
choco install kubernetes-cli

# Or using winget
winget install Kubernetes.kubectl

# Or download manually
curl.exe -LO "https://dl.k8s.io/release/v1.28.0/bin/windows/amd64/kubectl.exe"

# Add to PATH and verify
kubectl version --client

macOS

# Using Homebrew (Recommended)
brew install kubectl

# Or download binary
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# Verify
kubectl version --client

Linux

# Download latest stable version
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# Install
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Verify
kubectl version --client

# Enable kubectl autocomplete
echo 'source <(kubectl completion bash)' >>~/.bashrc
source ~/.bashrc

---

Option 1: Minikube (All Platforms)

Minikube runs a single-node Kubernetes cluster in a VM or container.

Windows 11

# Using Chocolatey
choco install minikube

# Or using winget
winget install Kubernetes.minikube

# Or download installer
# Visit: https://minikube.sigs.k8s.io/docs/start/

# Start Minikube
minikube start --driver=docker

# Verify
kubectl get nodes
minikube status

macOS

# Using Homebrew
brew install minikube

# Start Minikube
minikube start --driver=docker

# For Apple Silicon
minikube start --driver=docker --container-runtime=containerd

# Verify
kubectl get nodes
minikube status

Linux

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

# Start Minikube
minikube start --driver=docker

# Verify
kubectl get nodes
minikube status

Minikube Useful Commands

# Start with specific Kubernetes version
minikube start --kubernetes-version=v1.28.0

# Start with more resources
minikube start --cpus=4 --memory=8192

# Enable addons
minikube addons enable metrics-server
minikube addons enable dashboard
minikube addons enable ingress

# Access dashboard
minikube dashboard

# SSH into node
minikube ssh

# Stop/Delete
minikube stop
minikube delete

---

Option 2: kind (Kubernetes in Docker)

kind runs Kubernetes clusters using Docker containers as nodes.

Windows 11

# Using Chocolatey
choco install kind

# Or download binary
curl.exe -Lo kind-windows-amd64.exe https://kind.sigs.k8s.io/dl/v0.20.0/kind-windows-amd64
Move-Item .\kind-windows-amd64.exe c:\windows\system32\kind.exe

# Create cluster
kind create cluster --name dev-cluster

# Verify
kubectl cluster-info --context kind-dev-cluster

macOS

# Using Homebrew
brew install kind

# Create cluster
kind create cluster --name dev-cluster

# Verify
kubectl cluster-info --context kind-dev-cluster

Linux

# Download and install
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# Create cluster
kind create cluster --name dev-cluster

# Verify
kubectl cluster-info --context kind-dev-cluster

kind Multi-Node Cluster

Create kind-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    kubeadmConfigPatches:
      - |
        kind: InitConfiguration
        nodeRegistration:
          kubeletExtraArgs:
            node-labels: "ingress-ready=true"
    extraPortMappings:
      - containerPort: 80
        hostPort: 80
        protocol: TCP
      - containerPort: 443
        hostPort: 443
        protocol: TCP
  - role: worker
  - role: worker
  - role: worker

# Create multi-node cluster
kind create cluster --name multi-node --config kind-config.yaml

# List clusters
kind get clusters

# Delete cluster
kind delete cluster --name multi-node

---

Option 3: Docker Desktop (Windows & Mac)

Enable Kubernetes in Docker Desktop

1. Open Docker Desktop
2. Go to Settings → Kubernetes
3. Check "Enable Kubernetes"
4. Click "Apply & Restart"
5. Wait for Kubernetes to start (green indicator)

Verify

kubectl config get-contexts
kubectl config use-context docker-desktop
kubectl get nodes

Benefits

• ✅ Simplest setup
• ✅ Integrated with Docker Desktop
• ✅ Single-node cluster
• ✅ Good for development

---

Option 4: k3s (Lightweight Kubernetes)

k3s is a lightweight Kubernetes distribution perfect for edge, IoT, and resource-constrained environments.

Linux Installation

# Install k3s server
curl -sfL https://get.k3s.io | sh -

# Check status
sudo systemctl status k3s

# Get kubeconfig
sudo cat /etc/rancher/k3s/k3s.yaml

# Set KUBECONFIG
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
# Or copy to default location
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER ~/.kube/config

# Verify
kubectl get nodes

Add Worker Nodes

On server:

# Get token
sudo cat /var/lib/rancher/k3s/server/node-token

On worker nodes:

curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -

Windows (via WSL2)

# Install WSL2 Ubuntu
wsl --install -d Ubuntu

# Inside WSL2
curl -sfL https://get.k3s.io | sh -

k3s Configuration

# Install with custom options
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable traefik --disable servicelb" sh -

# Uninstall
/usr/local/bin/k3s-uninstall.sh

---

Option 5: kubeadm (Production Setup)

kubeadm helps set up production-grade Kubernetes clusters.

Prerequisites (All Nodes)

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

# Load kernel modules
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# Set 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

Install Container Runtime (containerd)

# Install containerd
sudo apt-get update
sudo apt-get install -y containerd

# Configure containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# Edit config to use systemd cgroup
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

# Restart containerd
sudo systemctl restart containerd
sudo systemctl enable containerd

Install kubeadm, kubelet, kubectl

# Add Kubernetes repo
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# Install packages
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

# Enable kubelet
sudo systemctl enable --now kubelet

Initialize Control Plane

# Initialize cluster (on master node)
sudo kubeadm init --pod-network-cidr=10.244.0.0/16

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

# Verify
kubectl get nodes

Install Pod Network (Calico)

# Install Calico CNI
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.0/manifests/tigera-operator.yaml
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.0/manifests/custom-resources.yaml

# Watch pods come up
kubectl get pods -n calico-system -w

Join Worker Nodes

Run on worker nodes (use token from init output):

sudo kubeadm join <control-plane-host>:6443 --token <token> \
    --discovery-token-ca-cert-hash sha256:<hash>

# If token expired, generate new one on master:
kubeadm token create --print-join-command

---

Option 6: Managed Kubernetes Services

AWS EKS

# Install eksctl
curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
sudo mv /tmp/eksctl /usr/local/bin

# Create cluster
eksctl create cluster \
  --name production-cluster \
  --region us-east-1 \
  --nodegroup-name standard-workers \
  --node-type t3.medium \
  --nodes 3

# Configure kubectl
aws eks update-kubeconfig --region us-east-1 --name production-cluster

Google GKE

# Install gcloud CLI
# Visit: https://cloud.google.com/sdk/docs/install

# Create cluster
gcloud container clusters create production-cluster \
  --zone us-central1-a \
  --num-nodes 3 \
  --machine-type n1-standard-2

# Get credentials
gcloud container clusters get-credentials production-cluster --zone us-central1-a

Azure AKS

# Install Azure CLI
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Login
az login

# Create resource group
az group create --name myResourceGroup --location eastus

# Create AKS cluster
az aks create \
  --resource-group myResourceGroup \
  --name production-cluster \
  --node-count 3 \
  --enable-addons monitoring \
  --generate-ssh-keys

# Get credentials
az aks get-credentials --resource-group myResourceGroup --name production-cluster

---

Verification & Testing

Basic Commands

# Check cluster info
kubectl cluster-info

# List nodes
kubectl get nodes

# Check system pods
kubectl get pods -A

# Create test deployment
kubectl create deployment nginx --image=nginx
kubectl get deployments
kubectl get pods

# Expose deployment
kubectl expose deployment nginx --port=80 --type=NodePort
kubectl get services

# Clean up
kubectl delete deployment nginx
kubectl delete service nginx

Deploy Sample Application

# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: LoadBalancer

kubectl apply -f nginx-deployment.yaml
kubectl get all
kubectl describe service nginx-service

---

Essential Tools & Add-ons

Helm (Package Manager)

# Install Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Verify
helm version

# Add repos
helm repo add stable https://charts.helm.sh/stable
helm repo update

K9s (Terminal UI)

# macOS
brew install k9s

# Linux
curl -sS https://webinstall.dev/k9s | bash

# Windows
choco install k9s

# Run
k9s

kubectx and kubens

# Switch between contexts and namespaces easily
brew install kubectx

# Usage
kubectx                    # List contexts
kubectx docker-desktop     # Switch context
kubens kube-system         # Switch namespace

---

Troubleshooting

Cluster Not Starting

# Check Docker
docker ps

# Check Minikube logs
minikube logs

# Check kind logs
docker logs kind-control-plane

# Reset cluster
minikube delete && minikube start
kind delete cluster && kind create cluster

kubectl Connection Issues

# Check context
kubectl config current-context
kubectl config get-contexts

# Switch context
kubectl config use-context minikube

# Verify connectivity
kubectl cluster-info
kubectl get nodes

Node Not Ready

# Describe node
kubectl describe node <node-name>

# Check kubelet logs (on node)
sudo journalctl -u kubelet -f

# Check pod network
kubectl get pods -n kube-system

Clean Up Resources

# Delete all resources in namespace
kubectl delete all --all -n default

# Force delete stuck pod
kubectl delete pod <pod-name> --grace-period=0 --force

# Clean up failed pods
kubectl delete pods --field-selector status.phase=Failed -A

---

Best Practices

✅ Use namespaces for organization
✅ Set resource limits on all pods
✅ Use RBAC for access control
✅ Enable logging and monitoring
✅ Regular backups of cluster state
✅ Keep clusters updated
✅ Use GitOps for deployments
✅ Implement security policies

---

Next Steps

✅ Kubernetes Installed!

Continue your journey:

• Kubernetes Best Practices
• Install Docker
• Platform Engineering Tools
• Official Kubernetes Documentation

Additional Resources

• Kubernetes Documentation
• kubectl Cheat Sheet
• Kubernetes Patterns
• CNCF Landscape