## Core Concepts Kubernetes (often abbreviated as **K8s**) is a container orchestration system that manages distributed applications at scale. It abstracts the complexity of individual machines and provides a unified API to declare *desired state*. ### Desired vs Actual State - You declare the **desired state** (e.g., “I want 3 replicas of this web app running with image nginx:1.27”). - Kubernetes controllers continuously reconcile this with the **actual state** (what is really running in the cluster). - If a Pod crashes or a node goes down, the controller will automatically create replacements to match the declared state. ``` User (YAML) ──► API Server ──► Controllers ──► Scheduler ──► Nodes/Pods ``` ### Pods - Smallest deployable unit in Kubernetes. - A Pod wraps one or more tightly coupled containers that: - Share the same **network namespace** (same IP/port space). - Can share storage volumes. - Example: a Pod running an application container and a sidecar logging container. ### Nodes - **Worker nodes**: Machines (VMs or physical) that run Pods. Each node has: - **kubelet**: agent that communicates with control plane. - **container runtime**: e.g., containerd, CRI-O, or Docker. - **kube-proxy**: handles networking rules for Services. - **Control plane nodes**: run cluster services like API server, etcd, scheduler, and controller manager. ### Controllers Controllers are Kubernetes processes that ensure the cluster state matches the desired state: - **Deployment Controller** → ensures desired number of Pods, manages rollouts/rollbacks. - **ReplicaSet Controller** → maintains stable replica count for Pods. - **StatefulSet Controller** → provides identity & stable storage for stateful workloads. - **DaemonSet Controller** → ensures one Pod runs per node (e.g., logging agents). ### Services - Provide stable networking endpoints for Pods (which are ephemeral and may change IPs). - Types: - **ClusterIP** (default) – internal-only virtual IP. - **NodePort** – exposes on each node’s IP with a static port. - **LoadBalancer** – integrates with cloud provider LB. - Services perform **basic load balancing** across Pods with matching labels. ### Labels & Selectors - **Labels**: arbitrary key-value pairs assigned to objects (`app=nginx`, `env=prod`). - **Selectors**: queries that match labels (`matchLabels: { app: nginx }`). - Controllers and Services use selectors to target specific Pods. ### Namespaces - Logical partitions of a cluster. Useful for: - Separating environments (dev, staging, prod). - Scoping RBAC permissions. - Resource quotas. ### Key Analogy Think of Kubernetes as an **operating system for your data center**: - **Cluster** = machine - **Node** = CPU core - **Pod** = process - **Service** = network socket - **ConfigMap/Secret** = environment variables - **Controller** = init/systemd keeping processes alive ## Cluster Building Blocks This section explains the **YAML anatomy** of the most common objects and then gives runnable examples. ### YAML Anatomy (What each field means) Most Kubernetes manifests share these top‑level keys: - `apiVersion`: Which API group/version this object uses (e.g., `v1`, `apps/v1`). - `kind`: The object type (e.g., `Pod`, `Deployment`, `Service`). - `metadata`: Identifying data like `name`, `namespace`, and `labels`. - `spec`: The desired state. Each `kind` has its own fields under `spec`. Common sub-fields you’ll see repeatedly: - **Labels & Selectors** - `metadata.labels`: tags you attach to objects. - `spec.selector`: how controllers/services find their target pods (usually matches `template.metadata.labels`). - **Pod Template (`template`)** - Found in controllers like `Deployment`, `StatefulSet`, `DaemonSet`. - It contains the `metadata.labels` and Pod `spec` for the pods that the controller will create. - **Containers** - `image`: container image (pin by tag or digest). - `ports`: `containerPort` values for discovery/probing. - `env`, `envFrom`: environment variables. - `resources`: `requests` (scheduler hints) and `limits` (enforced ceilings). - `livenessProbe`, `readinessProbe`, `startupProbe`: for health/traffic gating. - `volumeMounts`: mount points for declared volumes. - **Volumes** - Declared at the pod level (`spec.volumes`) and mounted by containers. - **Update Strategy** - Deployments default to `RollingUpdate` with `maxUnavailable`/`maxSurge` knobs. ### Pod (minimal) ```yaml apiVersion: v1 kind: Pod metadata: name: hello-pod labels: app: hello spec: containers: - name: web image: nginx:1.27 ports: - containerPort: 80 ``` **Notes:** `labels.app=hello` lets Services/ReplicaSets target this Pod. `containerPort=80` documents exposure. ### ReplicaSet You don’t have to write the ReplicaSet YAML in your manifests, usually managed by a Deployment ```yaml apiVersion: apps/v1 kind: ReplicaSet metadata: name: hello-rs spec: replicas: 3 selector: matchLabels: app: hello template: metadata: labels: app: hello spec: containers: - name: web image: nginx:1.27 ports: - containerPort: 80 ``` **Selector rule:** `selector.matchLabels` must match `template.metadata.labels`. ### Deployment (stateless, rolling updates) ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: hello-deploy spec: replicas: 3 selector: matchLabels: app: hello strategy: type: RollingUpdate rollingUpdate: maxUnavailable: 1 maxSurge: 1 template: metadata: labels: app: hello version: v1 spec: containers: - name: web image: nginx:1.27 ports: - containerPort: 80 resources: requests: { cpu: "50m", memory: "64Mi" } limits: { cpu: "250m", memory: "256Mi" } ``` ### Service (stable virtual IP + load balancing) ```yaml apiVersion: v1 kind: Service metadata: name: hello-svc spec: selector: app: hello ports: - port: 80 targetPort: 80 ``` **External access options:** set `type: NodePort` or `type: LoadBalancer`, or use **Ingress** for HTTP routing. ### Ingress (optional, L7 HTTP routing) ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: hello-ingress annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: rules: - host: hello.local http: paths: - path: / pathType: Prefix backend: service: name: hello-svc port: number: 80 ``` Requires an Ingress Controller (e.g., ingress‑nginx). For local clusters, map `hello.local` to a node IP in `/etc/hosts`. ## Workload Types - **Deployment** – stateless applications, declarative rollouts. - **StatefulSet** – stable identities/storage for stateful apps. - **DaemonSet** – one Pod per node (agents). - **Job/CronJob** – one‑off and scheduled tasks. ## Networking & Exposure - **Service** types: `ClusterIP` (default, internal), `NodePort`, `LoadBalancer`. - **Ingress** provides host/path routing at L7 with TLS termination when configured. ## Configuration & Secrets - **ConfigMap** and **Secret** provide configuration and sensitive data to Pods via env vars or mounted files. ## Storage - **PVC/PV/StorageClass** enable persistent storage. Access modes vary by storage backend. ## RBAC & Namespaces - Use namespaces for isolation and RBAC for least privilege access. ## Deploy, Update, Rollback ```bash kubectl apply -f deployment.yaml kubectl rollout status deploy/hello-deploy kubectl set image deploy/hello-deploy web=nginx:1.27.2 kubectl rollout undo deploy/hello-deploy ``` ## Full "Hello" App — Complete YAML Files Below are complete, ready‑to‑apply manifests. You can use **either** the NodePort route (no Ingress needed) **or** the Ingress route. **hello.yaml** ```yaml apiVersion: v1 kind: Namespace metadata: name: demo --- apiVersion: v1 kind: ConfigMap metadata: name: hello-www namespace: demo data: index.html: | Hello World

👋 Hello, Kubernetes!

This page is served by nginx in the demo namespace.

--- apiVersion: apps/v1 kind: Deployment metadata: name: hello-deploy namespace: demo spec: replicas: 2 selector: matchLabels: app: hello template: metadata: labels: app: hello spec: containers: - name: nginx image: nginx:1.27-alpine ports: - containerPort: 80 volumeMounts: - name: web mountPath: /usr/share/nginx/html/index.html subPath: index.html readinessProbe: httpGet: path: / port: 80 initialDelaySeconds: 2 periodSeconds: 5 livenessProbe: httpGet: path: / port: 80 initialDelaySeconds: 5 periodSeconds: 10 volumes: - name: web configMap: name: hello-www items: - key: index.html path: index.html --- apiVersion: v1 kind: Service metadata: name: hello-svc namespace: demo spec: type: NodePort selector: app: hello ports: - name: http port: 80 targetPort: 80 nodePort: 30080 ``` ### Start minikube ```bash minikube start --driver=docker kubectl config use-context minikube minikube status kubectl cluster-info ``` ### Apply the manifests ```bash kubectl apply -f hello.yaml ``` ### Verify the rollout ```bash kubectl get all -n demo kubectl rollout status deploy/hello-deploy -n demo kubectl describe svc hello-svc -n demo kubectl get events --sort-by=.lastTimestamp -n demo | tail -n 20 ``` ### Open the site ```bash minikube service hello-svc -n demo # or just print the URL: minikube service hello-svc -n demo --url ``` ### Debugging ```bash kubectl logs -n demo deploy/hello-deploy kubectl describe pod -n demo ``` ### Make a change ```bash # edit hello.yaml -> change the HTML in index.html kubectl apply -f hello.yaml # ensure pods pick up changes (ConfigMap mounted via subPath -> restart rollout) kubectl rollout restart deploy/hello-deploy -n demo kubectl get pods -o wide -n demo ``` ### Clean updates ```bash kubectl delete ns demo minikube stop # optional: remove cluster minikube delete ``` ### (Optional) Add Ingress Controller (NGINX) An API object that manages HTTP and HTTPS routing rules to Services inside the cluster. **Enable the NGINX Ingress controller add-on** ```bash minikube addons enable ingress kubectl get pods -n ingress-nginx ``` **hello-ingress.yaml** ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: hello-ing namespace: demo annotations: nginx.ingress.kubernetes.io/rewrite-target: / spec: ingressClassName: nginx rules: - host: hello.local http: paths: - path: / pathType: Prefix backend: service: name: hello-svc port: number: 80 ``` **Apply** ```bash kubectl apply -f hello-ingress.yaml ``` ## Troubleshooting Cheatsheet ### 1. `kubectl` Built-ins - `kubectl get events --sort-by=.lastTimestamp -A` → show recent events across all namespaces. - `kubectl top pod,node` → resource usage (requires `metrics-server`). - `kubectl port-forward pod/hello-pod 8080:80` → connect to a Pod locally for debugging. - `kubectl debug pod/hello-pod -it --image=busybox` → start an ephemeral debug container inside an existing Pod. ### 2. Debug Pods (toolbox containers) Launch a short-lived Pod with debugging tools: ```bash kubectl run -it --rm debug --image=nicolaka/netshoot --restart=Never -- sh ``` Examples inside the pod: ```sh dig hello-svc curl http://hello-svc traceroute hello-svc ``` ### 3. Logs & Probes - View container logs with `kubectl logs POD -c CONTAINER`. - Use `--previous` to view logs of a crashed container. - Check readiness/liveness probes to see why Pods are restarting or marked unready. ### 4. Node-level Checks - `kubectl describe node NODE` → see node conditions (disk pressure, memory pressure, taints). - `kubectl get pods -o wide` → check Pod-to-node mapping. - On the node: use `crictl ps` (container runtime) to inspect running containers. ### 5. Observability & Visualization Tools - **Lens** – Kubernetes IDE with dashboards. - **k9s** – terminal UI for browsing workloads and logs. - **stern** / **kubetail** – stream logs from multiple Pods by label selector. - **Octant** – local dashboard for workload visualization. - **Prometheus + Grafana** – monitoring and alerting. - **ELK/EFK stack** – centralized log aggregation. ### 6. Debugging Network Issues - Use debug containers with `tcpdump`, `ip route`, `ss`, `netstat`. - Inspect and test **NetworkPolicies** to ensure traffic is not blocked unintentionally. - Verify DNS resolution with `kubectl exec POD -- nslookup hello-svc`. ### 7. Validating Manifests - Dry-run before applying ```bash kubectl apply -f deployment.yaml --dry-run=client -o yaml ``` - Inspect schema and fields: ```bash kubectl explain deployment.spec.template.spec.containers ```