Kubernetes: Complete In-Depth Documentation

1. Introduction
Kubernetes (also known as K8s) is an open-source platform designed to automate deploying, scaling, and operating application containers.
π Why Kubernetes?
Container orchestration at scale.
Self-healing: Automatically restarts failed containers.
Scaling: Automatically scales up/down based on traffic.
Rolling Updates: Updates services without downtime.
Resource Optimization: Efficient use of CPU/memory.
π Core Concepts:
Concept | Description |
Pod | Smallest deployable unit, wraps one or more containers |
Service | Network access to pods |
Deployment | Declarative pod and replica management |
Namespace | Logical grouping |
Node | Worker machine (VM or physical) |
Volume | Persistent storage |
2. How to Download and Install Kubernetes (Local Setup)
You can set up Kubernetes using several methods. For learning purposes, the most common and easiest is Minikube.
Option 1: Minikube (for Local Kubernetes Cluster)
π§ Step-by-Step Installation on Windows:
You need Windows 10+, VirtualBox or WSL2, and PowerShell or Terminal.
Install Steps:
π₯ Step 1: Install kubectl (CLI to talk to Kubernetes)
bashCopyEdit# Windows - PowerShell
choco install kubernetes-cli
# macOS
brew install kubectl
# Linux (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install -y kubectl
π₯ Step 2: Install Minikube
bashCopyEdit# Windows
choco install minikube
# macOS
brew install minikube
# Linux
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
π Step 3: Start Minikube
bashCopyEditminikube start
π This downloads the required Kubernetes images and creates a local cluster using VirtualBox or Docker.
π§ If using WSL2:
bashCopyEditminikube start --driver=docker
π Step 4: Verify Your Kubernetes Cluster
bashCopyEditkubectl version --client
kubectl get nodes
kubectl cluster-info
β Option 2: kubeadm (for Real Production Setup)
If you're building a production setup on your own VMs or servers (Ubuntu preferred):
π Prerequisites
2 or more Linux servers (1 master, 1+ worker)
Swap off (
sudo swapoff -a
)Container runtime (containerd/Docker)
π₯ Installation
bashCopyEdit# On all nodes
sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates curl
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
sudo bash -c 'cat <<EOF >/etc/apt/sources.list.d/kubernetes.list
deb https://apt.kubernetes.io/ kubernetes-xenial main
EOF'
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
π Master Node Initialization
bashCopyEditsudo kubeadm init --pod-network-cidr=192.168.0.0/16
# After success, 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
π§© Install CNI Plugin (example: Calico)
bashCopyEditkubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
π Join Worker Nodes
Run the kubeadm join ...
command shown after init
on each worker node.
3. Kubernetes Architecture
Kubernetes follows a master-worker architecture, where the Control Plane (Master Node) manages the Worker Nodes.
π― Main Components
πΉ Control Plane Components:
Component | Role |
kube-apiserver | Frontend to the control plane; accepts REST commands via kubectl |
etcd | Key-value store used for storing all cluster data |
kube-scheduler | Assigns newly created pods to nodes |
kube-controller-manager | Runs controller processes like node, replication, endpoints |
cloud-controller-manager | Connects cluster to cloud provider APIs (optional) |
πΈ Node Components:
Component | Role |
kubelet | Communicates with API server, runs containers via CRI |
kube-proxy | Maintains network rules for Pod communication |
container runtime | Docker, containerd, or CRI-O |
ποΈ Cluster Layout:
[ User ] --> [ kubectl ] --> [ kube-apiserver ] --> [ etcd ]
|
----------------------------
| | | | |
[scheduler][controller][cloud mgr]
--> Worker Nodes
--> [kubelet + container runtime + kube-proxy + pods]
4. Deploying Your First App in Kubernetes
π Step-by-Step YAML for Deployment
# app-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:latest
ports:
- containerPort: 80
π Exposing the App as a Service
# app-service.yaml
apiVersion: v1
kind: Service
metadata:
name: nginx-service
spec:
type: NodePort
selector:
app: nginx
ports:
- protocol: TCP
port: 80
targetPort: 80
nodePort: 30007
π§ͺ Apply Deployment
kubectl apply -f app-deployment.yaml
kubectl apply -f app-service.yaml
kubectl get pods
kubectl get svc
5. Kubernetes Networking
πΈοΈ Pod-to-Pod Communication
All Pods get a unique IP.
Uses CNI plugin like Calico or Flannel.
π Service Types
Type | Description |
ClusterIP | Default. Internal communication only |
NodePort | Exposes service on node IP:port |
LoadBalancer | For cloud providers only |
π Ingress Controller
Used to expose HTTP/HTTPS routes with domain-level routing.
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.6.4/deploy/static/provider/cloud/deploy.yaml
6. Kubernetes Storage
πΉ Volumes
- Volumes are attached to pods and persist data.
Example:
volumeMounts:
- mountPath: "/data"
name: data-volume
volumes:
- name: data-volume
emptyDir: {}
πΉ Persistent Volumes (PV) and Persistent Volume Claims (PVC)
# pv.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
name: my-pv
spec:
capacity:
storage: 1Gi
accessModes:
- ReadWriteOnce
hostPath:
path: "/mnt/data"
# pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
7. Kubernetes Security
π RBAC (Role-Based Access Control)
# rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: default
name: pod-reader
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "watch", "list"]
# role-binding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: read-pods
namespace: default
subjects:
- kind: User
name: jane
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: Role
name: pod-reader
apiGroup: rbac.authorization.k8s.io
π‘οΈ Secrets
apiVersion: v1
kind: Secret
metadata:
name: db-secret
stringData:
username: admin
password: secret123
8. Monitoring & Logging
π Metrics Server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
kubectl top pods
π Prometheus + Grafana
- Use Helm chart:
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install k8s-monitor prometheus-community/kube-prometheus-stack
9. Helm (Kubernetes Package Manager)
π§ Install Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
π¦ Use a Helm Chart
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install my-nginx bitnami/nginx
10. Troubleshooting
π§ͺ Useful Commands
kubectl get all
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl exec -it <pod-name> -- /bin/bash
π§Ή Clean Up
kubectl delete deployment nginx-deployment
kubectl delete svc nginx-service
Summary
Kubernetes is a powerful orchestration platform. With Minikube, Helm, and YAML files, you can build and manage scalable containerized applications locally or in production.
Next Step: Learn about CI/CD integration with Kubernetes using GitHub Actions or ArgoCD.
11. References
Subscribe to my newsletter
Read articles from Arijit Das directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
