Kubernetes: Complete In-Depth Documentation

Arijit DasArijit Das
6 min read

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:

ConceptDescription
PodSmallest deployable unit, wraps one or more containers
ServiceNetwork access to pods
DeploymentDeclarative pod and replica management
NamespaceLogical grouping
NodeWorker machine (VM or physical)
VolumePersistent 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:

ComponentRole
kube-apiserverFrontend to the control plane; accepts REST commands via kubectl
etcdKey-value store used for storing all cluster data
kube-schedulerAssigns newly created pods to nodes
kube-controller-managerRuns controller processes like node, replication, endpoints
cloud-controller-managerConnects cluster to cloud provider APIs (optional)

πŸ”Έ Node Components:

ComponentRole
kubeletCommunicates with API server, runs containers via CRI
kube-proxyMaintains network rules for Pod communication
container runtimeDocker, 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

TypeDescription
ClusterIPDefault. Internal communication only
NodePortExposes service on node IP:port
LoadBalancerFor 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

0
Subscribe to my newsletter

Read articles from Arijit Das directly inside your inbox. Subscribe to the newsletter, and don't miss out.

Written by

Arijit Das
Arijit Das