Complete guide to container orchestration β from architecture to operations
βΈοΈ Kubernetes Complete Guide
From why Kubernetes is needed, through the Control Plane, Worker Node, network, storage, and security structure, building a cluster with kubeadm, setting up the Gateway API and monitoring, to the whole deployment flow and practical comparisons and checklists β a complete guide, with diagrams, to understanding Kubernetes as one distributed platform.
Intermediate
Updated Oct 1, 2026
~46 min read
28 sections
34 code examples
Web IDE lab included
βΈοΈ
Kubernetes Web IDE
Run code in the browser with nothing to install and learn through step-by-step examples.
Understanding cluster architecture & building one yourselfOperating Deployments & ServicesDesigning Gateway API, network, storage, and security structureSetting up a monitoring stack & mapping the deployment flow
From why Kubernetes is needed, through the Control Plane, Worker Node, network, storage, and security structure, building a cluster with kubeadm, setting up the Gateway API and monitoring, to the whole deployment flow and practical comparisons and checklists β a complete guide, with diagrams, to understanding Kubernetes as one distributed platform. Rather than listing concepts, this guide is organized so you can follow the content in the order you have to make decisions on a real project.
Key perspective
Infrastructure / operations
Rather than memorizing install commands, understand the order in which traffic, runtime, observability, and incident response connect.
Understanding cluster architecture & building one yourselfOperating Deployments & ServicesDesigning Gateway API, network, storage, and security structureSetting up a monitoring stack & mapping the deployment flow
Architecture diagrams
To make what you read stick, it helps to capture the flow as a picture first. The two diagrams below are reference maps you can keep coming back to while learning Kubernetes.
Learning flow
Rendering diagramβ¦
Architecture view
Rendering diagramβ¦
What is Kubernetes?
When you first open Kubernetes, the big picture matters more than individual commands. This section starts with the problems the concepts ahead were created to solve.
Kubernetes (K8s) is a container orchestration platform that automatically deploys, scales, heals, and operates applications packaged as containers across many servers (nodes). At its heart is the declarative management model: you only declare "keep it in this state" and the system takes care of the rest.
In traditional server operations, administrators logged in to each server to deploy applications, restarted things themselves when they failed, and added servers by hand when traffic grew. VM-based operations raised flexibility by virtualizing hardware, but the boot time, resource overhead, and image size problems of the VM itself remained. Docker solved the problem of "running identically everywhere" by packaging applications as containers, but it did not answer the question of who coordinates containers, and how, when they are spread across many servers. Kubernetes fills in exactly this last piece of the puzzle β if Docker is the tool for running one container well, Kubernetes is the tool for running hundreds to thousands of containers reliably across many servers.
Problem Kubernetes solves
Limits of the traditional way
The Kubernetes approach
Deployment automation
Manual SSH deploys, reliance on scripts, a different procedure per person
Declare the desired state with a Deployment β a controller rolls it out automatically
Scalability
Adding and configuring servers by hand, repeatedly, as traffic grows
Metric-based automatic scaling with HPA/Cluster Autoscaler
Failure recovery
When a process dies, a person notices and restarts it
The kubelet watches continuously and restarts automatically on failure (self-healing)
Service discovery
Hardcoded IPs, or building a separate registry yourself
Automatic name-based discovery with Service + CoreDNS
Standardized operations
A different deployment method per team and per server
Every workload described the same way in the common language of YAML manifests
Declarative management
Describing "what to do" as a sequence of commands (imperative)
Declare only "what state it should be in" β the current state keeps converging on it (reconcile)
The whole service flow at a glance
Here you look at The whole service flow at a glance alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Before learning the components one by one, let us start with the big picture of the path a single user request actually takes to reach a Pod. When a user types a domain into the browser, β DNS resolves that domain to the IP of the cloud LoadBalancer, and β‘ the browser sends an HTTPS request to that IP. β’ The LoadBalancer passes this traffic to the Gateway layer of the cluster.
In this guide the Gateway layer is implemented with Contour. What actually handles the traffic and terminates TLS is the data plane, Envoy Proxy, while Contour itself is a control plane that does not sit in the traffic path β Contour watches the routing rules declared as HTTPRoute (the Gateway API standard) or HTTPProxy (a Contour-specific CRD), and when something changes, immediately translates it into configuration Envoy understands (xDS) and delivers it. β£ Using the rules it received, Envoy finds the Service that matches the request path and forwards the traffic. β€ The Service picks one actual Pod according to the rules kube-proxy manages and routes the traffic to it, and β₯ the Application Container in that Pod handles the request and produces the response. The response travels back to the user along exactly the same path. This single round trip is what happens inside K8s every time you visit a website.
Rendering diagramβ¦
Overall K8s architecture
Here you look at Overall K8s architecture alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A Kubernetes cluster is made up of the Control Plane, which controls the whole cluster, and the Worker Nodes, which run the actual workloads. Comparing the Control Plane to the human "brain" makes it easier to understand β just as the brain only decides and directs and does not move the limbs itself, the Control Plane only decides "what to place where", and the Worker Nodes do the actual running of containers. Because the roles are separated this way, Pods that are already running keep working normally even when the Control Plane fails (though "new decisions" such as new deployments and failure recovery stop). Conversely, when one Worker Node dies, the Pods on it die, but the Control Plane detects this and places them again on other healthy Nodes β this automatic recovery is the core value of Kubernetes.
Rendering diagramβ¦
Rendering diagramβ¦
Layer
Component
Role
Control Plane
kube-apiserver
The entry point for all kubectl/internal communication; serves the REST API β every other component must communicate through the API Server
Control Plane
etcd
The distributed key-value store holding the state of the whole cluster β in effect the single "source of truth" of the cluster
Control Plane
kube-scheduler
Decides which Worker Node a new Pod goes on (based on spare resources, affinity, taints, and so on)
Control Plane
kube-controller-manager
Loops that keep comparing the desired state of each resource (Deployment/ReplicaSet/Node and so on) with the current state and reconciling them
Control Plane
cloud-controller-manager
Integrates with cloud APIs such as AWS/GCP/Azure (LoadBalancer provisioning, volume attachment, and so on)
Worker Node
kubelet
Creates, deletes, and health-checks Pods as the API Server instructs β the only agent on the Node that talks to the API Server directly
Worker Node
kube-proxy
Manages the Service ClusterIP β Pod IP network rules (iptables/ipvs)
Worker Node
containerd
The container runtime β pulls images, runs containers
Worker Node
CNI Plugin
Network connectivity between Pods (Calico/Flannel/Cilium)
Add-on
CoreDNS
Resolves Service/Pod DNS names
Add-on
Metrics Server
Collects CPU and memory metrics for HPA/VPA
Add-on
Gateway Controller (formerly Ingress Controller)
An L7 proxy that routes external traffic to Services β Ingress is legacy; new setups use the Gateway API
Worker Nodes in detail β how a Pod actually gets run
Worker Nodes in detail β how a Pod actually gets run is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
A Worker Node has three core components. The kubelet is the "site supervisor" on the Node: it receives the Pod specs the API Server instructs, asks the container runtime to run them, and periodically checks container health (Liveness/Readiness Probes) to restart dead containers. kube-proxy manages the network rules of the Node (iptables/ipvs) so that traffic arriving at the ClusterIP of a Service is forwarded to an actual Pod IP. The container runtime (containerd and others) is the execution engine that actually pulls images and starts container processes.
To make the relationship between Node, Pod, and Container clear: a Node is one physical/virtual server on which containers run, a Pod is a group of one or more containers scheduled together on that Node (sharing the same network namespace and volumes), and a Container is the unit inside a Pod where a process actually runs. The Pod is the "smallest deployable unit" because Kubernetes handles scheduling, health checks, networking, and restarts all at the Pod level β there is no notion of restarting just one container separately or moving it to another Node; the whole Pod always moves together.
When a Node fails and stops responding, the Control Plane marks it NotReady after a set time (around 40 seconds by default) and then reschedules the Pods on it to other healthy Nodes. This rescheduling, however, applies only to Pods managed by a controller such as a Deployment/StatefulSet β a "naked Pod" created directly with no controller simply disappears along with the Node and does not come back.
Concept
Definition
Analogy
Node
A server on which containers actually run (a physical server or VM)
An apartment building
Pod
A group of one or more containers placed together on a Node. Shares network/volumes
Roommates living in the same apartment unit
Container
The unit inside a Pod where the actual process runs (1 image = 1 container)
One person in a room
Core resource concepts & relationships
Here you look at Core resource concepts & relationships alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
This section lays out the roles and relationships of the resources you use most when first meeting K8s. Resources are not independent of each other; they are joined by a loose link called the Label/Selector β a Service finds the set of Pods carrying a particular label and sends traffic to them, and a Deployment tracks the ReplicaSets it created by label. This principle of "connect by label, not by name" runs through the entire Kubernetes resource model.
Rendering diagramβ¦
Resource
Description
Main use
Pod
The smallest deployable unit, a group of one or more containers
The unit that actually runs the app
ReplicaSet
Always keeps the number of Pods matching the given label at N
Created and managed automatically by a Deployment internally β you almost never create one directly
Deployment
Wraps ReplicaSets and manages rolling updates and rollback history too
The default controller for stateless apps
StatefulSet
Guarantees Pod ordering, stable network IDs, and independent storage
Stateful workloads such as databases and message brokers
DaemonSet
Deploys one Pod on every node (or every node matching a condition)
Log collectors, monitoring agents, CNI plugins
Job
A one-off task that has a completion (Completed) β retried until it succeeds
DB migrations, batch processing
CronJob
Creates Jobs periodically on a cron schedule
Nightly reports, regular backups
Namespace
A virtual cluster boundary that isolates resources logically
Separation by environment (dev/staging/prod) or team
Label / Selector
Key-value tags attached to resources and the query conditions that find them
The only way a Service, ReplicaSet, and so on find their target Pods
Annotation
Extra metadata that, unlike a Label, is not used in queries
Provides a stable endpoint for the set of Pods found by a Label Selector
ClusterIP/NodePort/LoadBalancer/Headless
Gateway API
The official K8s standard replacing Ingress with three layers: GatewayClass/Gateway/HTTPRoute
The default L7 routing approach for new clusters (Ingress is legacy)
ConfigMap
Non-sensitive configuration data
App config, scripts
Secret
Stored Base64-encoded (not encrypted β see the ConfigMap & Secret section for details)
Passwords, certificates, tokens
ServiceAccount
The identity a process inside a Pod uses when calling the API Server
The bridge connecting Pod β RBAC
PersistentVolume / Claim
An abstraction of a storage resource / the spec by which a Pod requests a PV
Workloads that need data persistence
HPA
Adjusts the number of Pods automatically based on metrics such as CPU/memory
Responding to traffic swings
RBAC (Role/RoleBinding and so on)
Controls API access rights per ServiceAccount and user
Least-privilege separation per team and per workload
ResourceQuota / LimitRange
A cap on total resources per Namespace / default and maximum values per container
Preventing resource abuse in multi-tenant environments
Cluster build roadmap & package origins
Cluster build roadmap & package origins is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
This section details the whole lifecycle of building a Kubernetes cluster (from installation to operations), along with the origin and maintainer of each package/source downloaded during installation. Knowing these origin addresses and how safe the pipeline is matters for keeping a production environment consistent and intact.
OS upstream repositories (official Debian/Ubuntu and Rocky/RHEL mirrors)
Stage 2. Runtime install
Installing containerd for running containers and managing images, and configuring cgroups
The official Docker package repository (download.docker.com)
Stage 3. K8s tool install
Installing the kubeadm, kubelet, and kubectl packages and holding their versions
The official Kubernetes package repository (pkgs.k8s.io - Debian/RPM)
Stage 4. Cluster init
Setting up the Control Plane with kubeadm init, distributing the kubeconfig
k8s.gcr.io / registry.k8s.io (the official OCI image registry)
Stage 5. Network (CNI)
Connecting the L3 overlay network between Pods and applying network policies
Official CNI project releases (github.com/projectcalico/calico, cilium/cilium, and so on)
Stage 6. Services & ingress
Setting up a LoadBalancer / Ingress for external exposure and configuring TLS termination
Helm Artifact Hub and official project repositories (kubernetes/ingress-nginx)
Stage 7. Persistent volumes (CSI)
CSI integration for persistent storage for stateless/stateful Pods
Cloud vendor CSI (AWS, GCP, Azure) or open source (NFS, Longhorn, Ceph)
Stage 8. Running applications
Managing Deployments, StatefulSets, HPA, ConfigMaps/Secrets, and rolling updates
Your own container registry (AWS ECR, Docker Hub, GitHub Packages, and so on)
Stage 9. Monitoring & incident response
Metric collection with Prometheus and Grafana, plus Day-2 rollback and backup/restore operations
The Prometheus-Community Helm charts and the official upstream GitHub repositories
Preparing for installation β hardware Β· OS Β· network
Here you look at Preparing for installation β hardware Β· OS Β· network alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A checklist to go through before building an on-premises K8s cluster with kubeadm. A layout of at least 1 Control Plane + 2 Worker Nodes is recommended.
00-all-nodes.shBASH
#!/bin/bash# Run on every node (Control Plane + Worker alike)# 1. Set the hostname (different on each node)hostnamectl set-hostname k8s-master-01 # Worker: k8s-worker-01, k8s-worker-02# 2. Register every node in /etc/hostscat >> /etc/hosts << 'EOF'192.168.1.10 k8s-master-01192.168.1.11 k8s-worker-01192.168.1.12 k8s-worker-02EOF# 3. Disable swap (required β a kubelet requirement)swapoff -ased -i '/swap/d' /etc/fstab# 3-1. Disable SELinux (required on the RHEL/Rocky Linux family)if [ -f /etc/selinux/config ]; then setenforce 0 sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/configfi# 4. Load kernel modulescat > /etc/modules-load.d/k8s.conf << 'EOF'overlaybr_netfilterEOFmodprobe overlaymodprobe br_netfilter# 5. sysctl network parameterscat > /etc/sysctl.d/k8s.conf << 'EOF'net.bridge.bridge-nf-call-iptables = 1net.bridge.bridge-nf-call-ip6tables = 1net.ipv4.ip_forward = 1EOFsysctl --system# 6. Open firewall ports# [Debian/Ubuntu family - when using ufw]# Control Plane:# ufw allow 6443/tcp # API Server# ufw allow 2379:2380/tcp # etcd# ufw allow 10250/tcp # kubelet API# ufw allow 10259/tcp # kube-scheduler# ufw allow 10257/tcp # kube-controller-manager# Worker Node:# ufw allow 10250/tcp # kubelet API# ufw allow 30000:32767/tcp # NodePort range# ufw allow from 192.168.1.0/24 # allow the whole internal network# [RHEL/Rocky Linux family - when using firewalld]# Control Plane:# firewall-cmd --permanent --add-port=6443/tcp# firewall-cmd --permanent --add-port=2379-2380/tcp# firewall-cmd --permanent --add-port=10250/tcp# firewall-cmd --permanent --add-port=10259/tcp# firewall-cmd --permanent --add-port=10257/tcp# Worker Node:# firewall-cmd --permanent --add-port=10250/tcp# firewall-cmd --permanent --add-port=30000-32767/tcp# firewall-cmd --reload
01-containerd.shBASH
#!/bin/bash# Install containerd (every node - run the part for your Linux distribution)# ββ 1. Debian/Ubuntu family (APT) ββββββββββββββββif command -v apt-get &> /dev/null; then apt-get update apt-get install -y ca-certificates curl gnupg install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg chmod a+r /etc/apt/keyrings/docker.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | tee /etc/apt/sources.list.d/docker.list apt-get update apt-get install -y containerd.iofi# ββ 2. RHEL/Rocky Linux family (DNF) βββββββββββββif command -v dnf &> /dev/null && ! command -v apt-get &> /dev/null; then dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo dnf install -y containerd.iofi# ββ 3. Generate the default containerd config and enable SystemdCgroup ββmkdir -p /etc/containerdcontainerd config default > /etc/containerd/config.toml# Enable SystemdCgroup (to match the cgroup driver of the kubelet)sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.tomlsystemctl restart containerdsystemctl enable containerdsystemctl status containerd
02-kubeadm.shBASH
#!/bin/bash# Install kubeadm, kubelet, kubectl (every node - run the part for your Linux distribution)# ββ 1. Debian/Ubuntu family (APT) ββββββββββββββββif command -v apt-get &> /dev/null; then apt-get update apt-get install -y apt-transport-https ca-certificates curl gpg curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.36/deb/Release.key | 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.36/deb/ /" | tee /etc/apt/sources.list.d/kubernetes.list apt-get update apt-get install -y kubelet kubeadm kubectl apt-mark hold kubelet kubeadm kubectl # prevent automatic upgradesfi# ββ 2. RHEL/Rocky Linux family (DNF) βββββββββββββif command -v dnf &> /dev/null && ! command -v apt-get &> /dev/null; then cat <<EOF | tee /etc/yum.repos.d/kubernetes.repo[kubernetes]name=Kubernetesbaseurl=https://pkgs.k8s.io/core:/stable:/v1.36/rpm/enabled=1gpgcheck=1gpgkey=https://pkgs.k8s.io/core:/stable:/v1.36/rpm/repodata/repomd.xml.keyexclude=kubelet kubeadm kubectl cri-tools kubernetes-cniEOF dnf install -y kubelet kubeadm kubectl --disableexcludes=kubernetesfi# ββ 3. Enable the service ββββββββββββββββββββββββsystemctl enable --now kubelet# Check the versionskubeadm versionkubectl version --client
Item
Minimum spec
Recommended spec (production)
OS
Linux (Debian family: Ubuntu 22.04+ / RHEL family: Rocky Linux 9+)
Linux Enterprise (RHEL / Ubuntu FIPS)
Control Plane CPU
2 vCPU
4 vCPU (HA: 3 nodes Γ 4 vCPU)
Control Plane RAM
2 GB
8 GB
Worker Node CPU
2 vCPU
8+ vCPU (depending on the workload type)
Worker Node RAM
4 GB
16 GB+
Disk (Control Plane)
20 GB
100 GB SSD (etcd WAL performance)
Disk (Worker)
40 GB
200 GB+ SSD
Network
1 Gbps
10 Gbps (between nodes)
Pod CIDR
10.244.0.0/16 (Flannel)
10.244.0.0/16 or 192.168.0.0/16 (Calico)
Service CIDR
10.96.0.0/12
10.96.0.0/12 (cannot be changed β settle it before installing)
Building a cluster with kubeadm
Here you look at Building a cluster with kubeadm alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Proceed in the order Control Plane initialization β joining the Worker nodes β kubeconfig setup. All commands are based on Linux (Ubuntu 22.04 / Rocky Linux 9) and K8s v1.36.
03-init-control-plane.shBASH
#!/bin/bash# Run only on the Control Plane node# kubeadm init β the Pod CIDR must match your choice of CNI# Calico: 192.168.0.0/16 / Flannel: 10.244.0.0/16kubeadm init \ --control-plane-endpoint "k8s-master-01:6443" \ --pod-network-cidr=192.168.0.0/16 \ --service-cidr=10.96.0.0/12 \ --kubernetes-version=v1.36.0 \ --cri-socket unix:///run/containerd/containerd.sock \ 2>&1 | tee /root/kubeadm-init.log# Example output on success:# Your Kubernetes control-plane has initialized successfully!# kubeadm join k8s-master-01:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash># kubectl setup (regular user)mkdir -p $HOME/.kubecp -i /etc/kubernetes/admin.conf $HOME/.kube/configchown $(id -u):$(id -g) $HOME/.kube/config# Check the cluster status (NotReady, since the CNI is not installed yet)kubectl get nodeskubectl get pods -n kube-system
04-worker-join.shBASH
#!/bin/bash# Run on the Worker nodes# Run the join command copied from the kubeadm init outputkubeadm join k8s-master-01:6443 \ --token <your-token> \ --discovery-token-ca-cert-hash sha256:<your-hash># ββ How to reissue the token after it expires (24h) (on the Control Plane) ββββββββ# kubeadm token create --print-join-command
05-verify-cluster.shBASH
# Check the state of the whole cluster from the Control Plane# Node list (before the CNI: NotReady)kubectl get nodes -o wide# System Pod statuskubectl get pods -n kube-system# etcd health checkkubectl exec -n kube-system etcd-k8s-master-01 -- \ etcdctl endpoint health \ --cacert=/etc/kubernetes/pki/etcd/ca.crt \ --cert=/etc/kubernetes/pki/etcd/server.crt \ --key=/etc/kubernetes/pki/etcd/server.key# Check that the API Server responds (kubectl get componentstatuses is deprecated β /healthz?verbose is recommended)kubectl cluster-infokubectl get --raw='/healthz?verbose'
06-ha-control-plane.shBASH
# Add HA Control Plane nodes (for a 3-node HA layout)# Run on Control Plane #2 and #3# Use the --control-plane command from the kubeadm init outputkubeadm join k8s-master-01:6443 \ --token <token> \ --discovery-token-ca-cert-hash sha256:<hash> \ --control-plane \ --certificate-key <cert-key># Reissue the certificate-key (when expired)# kubeadm init phase upload-certs --upload-certs# Once HA is in place, the API Server must be load balanced# Configure HAProxy / keepalived / a cloud LB on the VIP (192.168.1.100:6443)# Set --control-plane-endpoint to the VIP or a DNS name
Kubernetes network structure
Here you look at Kubernetes network structure alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Kubernetes networking starts from one principle β every Pod can communicate directly with every other Pod without NAT (the flat network model). Whichever Node a Pod is on, its Pod IP must be unique across the cluster and reachable as-is. What actually implements this model is a CNI (Container Network Interface) plugin (Calico, Flannel, Cilium, and others) β CNI is not a particular product but a standard interface saying "implement the Pod network to this specification", and the cluster operator picks one and installs it.
Pod IPs and Node IPs are completely different address spaces. A Node IP is the fixed address of the server itself (e.g. 10.0.1.10), while a Pod IP is assigned from a separate virtual network range managed by the CNI (e.g. 10.244.1.5), and above all, the IP changes when a Pod is recreated. If Pod IPs change on every deployment, scaling event, and failure recovery, how can clients keep finding the Pod? Solving this problem is exactly what a Service is for β a Service finds its target set of Pods with a Label Selector and gives them one fixed virtual IP (ClusterIP) and a name.
Rendering diagramβ¦
Rendering diagramβ¦
Service type
How it works
Main use
ClusterIP (default)
Issues a virtual IP reachable only from inside the cluster
Communication between internal microservices
NodePort
Opens the same port (30000-32767) on every Node, reachable from outside at :
Simple tests, temporary exposure on-premises with no cloud LB
LoadBalancer
The cloud-controller-manager provisions a cloud LB automatically
The standard way of exposing services externally in the cloud
Headless (clusterIP: None)
Issues no virtual IP and returns the list of Pod IPs as-is on a DNS lookup
When each Pod needs to be reached individually, as with a StatefulSet
Ingress vs Gateway API β a comparison for beginners
Ingress vs Gateway API β a comparison for beginners is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
The classic Ingress packed everything into a single resource: host/path routing, TLS, and even controller-specific options (annotations). The problem was that these annotations differed from controller to controller (nginx, traefik, and so on), so there was no standard, and there was no good way to split permissions between the infrastructure team (domain and TLS management) and the app teams (path routing). The Gateway API splits this responsibility into three layers by role.
Layer
Who manages it
Responsibility
GatewayClass
Infrastructure/platform team (cluster administrators)
Defines which implementation to use (Contour, Envoy Gateway, and so on)
Gateway
Infrastructure/platform team
Entry point settings such as listener ports, domains, and TLS certificates
HTTPRoute
Application teams (each in its own namespace)
Defines the path and header routing rules to its own services
Installing the CNI & network plugin
Here you look at Installing the CNI & network plugin alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Without a CNI (Container Network Interface) plugin, nodes stay in the NotReady state. Choose between the two best-known options, Calico and Flannel. If you need network policies (NetworkPolicy), Calico is recommended.
# NetworkPolicy β example of isolation between Namespaces# Pods in the default namespace may communicate only within the same namespaceapiVersion: networking.k8s.io/v1kind: NetworkPolicymetadata: name: default-deny-ingress namespace: productionspec: podSelector: {} # applies to every Pod policyTypes: - Ingress---# Only the API server may access the DBapiVersion: networking.k8s.io/v1kind: NetworkPolicymetadata: name: allow-api-to-db namespace: productionspec: podSelector: matchLabels: app: postgres policyTypes: - Ingress ingress: - from: - podSelector: matchLabels: role: api-server ports: - port: 5432
coredns-check.shBASH
# Check CoreDNS and DNS resolutionkubectl get pods -n kube-system -l k8s-app=kube-dns# Test that DNS workskubectl run dns-test --image=busybox:1.36 --rm -it --restart=Never -- \ nslookup kubernetes.default# Service DNS name format# <service>.<namespace>.svc.cluster.local# Example: postgres-svc.database.svc.cluster.local
CNI
Pod CIDR
Network policy
Notes
Calico
192.168.0.0/16
Yes (full support)
BGP-based, suits large clusters, built-in IPAM
Flannel
10.244.0.0/16
No (separate install needed)
Simple configuration, small clusters
Cilium
Any
Yes + L7 policy
eBPF-based, high performance, built-in Hubble observability
WeaveNet
10.32.0.0/12
Yes
Supports encryption, small environments
Kubernetes storage structure
Here you look at Kubernetes storage structure alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Containers are stateless by default β files written inside a container disappear the moment the container (or the Pod wrapping it) is recreated. Pods are deleted and recreated all the time during deployment, scaling, and failure recovery, so data that must survive, such as a database or uploaded files, must not rely on the container filesystem alone. To solve this, Kubernetes treats storage as a separate object decoupled from the container lifecycle.
A PersistentVolume (PV) abstracts real storage (NFS, a cloud disk, a local disk, and so on) as a cluster object, and a PersistentVolumeClaim (PVC) is the spec by which an application (Pod) requests "this much capacity with this access mode". A StorageClass is a template for dynamic provisioning: instead of creating PVs in advance, it creates a PV suited to the backend automatically the moment a PVC is created β in practice this is used overwhelmingly more than static provisioning, where an administrator creates each PV by hand.
Rendering diagramβ¦
Backend
Characteristics
Good fit
Local Path
Uses the local disk of the Node directly β data is unreachable if the Node changes
Development environments, single-node tests
NFS
Several Nodes can mount the same volume at once (ReadWriteMany)
On-premises, when several Pods need to share files
Cloud disks (EBS/PD/Managed Disk and so on)
Reattached automatically when the Node changes (ReadWriteOnce)
Databases in the cloud, volumes dedicated to a single Pod
Storage setup β StorageClass & PV
Here you look at Storage setup β StorageClass & PV alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
An on-premises environment has no cloud provisioner, so install the local-path-provisioner (development/small scale) or the NFS Provisioner (production).
local-path.shBASH
# Install local-path-provisioner (single-node development environment)kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.28/deploy/local-path-storage.yaml# Mark it as the default StorageClasskubectl patch storageclass local-path \ -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'kubectl get storageclass
Here you look at Kubernetes security structure alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Every request coming into the API Server must pass through three stages in order. First is authentication β checking "who are you?" (a client certificate or OIDC token for users, a ServiceAccount token for Pods). Next is authorization β checking "are you allowed to do this?". The default Kubernetes authorization mechanism is RBAC. Finally, Admission Control verifies once more "does this request comply with policy?" (for example, forbidding privileged containers or restricting image sources), and only then is the request actually written to etcd. If any one of these three stages fails, the request is rejected immediately.
Grants Namespace-scoped (Role) or cluster-wide (ClusterRole) permissions to users and ServiceAccounts
Principle of least privilege β see the RBAC section of the K8s Advanced guide for detailed examples
ServiceAccount
The identity a process inside a Pod uses when calling the API Server
For Pods that do not use it, blocking automatic token mounting with automountServiceAccountToken: false is recommended
NetworkPolicy
Restricts traffic between Pods with an allowlist (the default is allow all)
Works only if the CNI supports NetworkPolicy β Flannel does not, Calico/Cilium do
Secret
Stores sensitive data (Base64) β not encryption in itself
See the ConfigMap & Secret section for details such as etcd Encryption at Rest and least-privilege RBAC
Image and registry security
Use only trusted registries, scan images for vulnerabilities (Trivy and others)
Avoid the latest tag; authenticate to private registries with imagePullSecrets
Pod Security (Admission)
Restricts privileged containers, the root user, hostPath mounts, and so on
The old PodSecurityPolicy has been removed β Pod Security Admission (PSA), based on Namespace labels, is used now
Gateway API & TLS setup (successor to Ingress)
Here you look at Gateway API & TLS setup (successor to Ingress) alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
The Ingress-NGINX project of the Kubernetes community officially reached end of life (EOL) on March 24, 2026, and no bug fixes or security patches are provided after that. The official Kubernetes documentation also recommends using the Gateway API instead of Ingress for new clusters. Instead of cramming every setting into a single Ingress resource, the Gateway API is the official K8s SIG-Network standard (the formal successor API to Ingress) that separates, by role, the GatewayClass/Gateway managed by infrastructure owners from the HTTPRoute managed by application teams. From here on this guide uses the Gateway API by default and keeps existing Ingress environments in a separate "Legacy" section.
The hands-on examples use Contour. Contour is a CNCF Incubating project built with Envoy Proxy as the data plane that handles the actual traffic, while Contour itself plays only the control plane role β it watches the Gateway API/HTTPProxy resources users create and, when something changes, translates it into the format Envoy understands (the xDS API) and delivers it in real time. Unlike NGINX Ingress, there is no need to reload worker processes when the configuration changes, so changes are applied with no downtime and no dropped connections even in environments with many routes. What makes Contour especially useful is that it supports both the Gateway API (HTTPRoute) and its own CRD, HTTPProxy, at the same time β choose HTTPRoute if you want to follow the standard, or HTTPProxy if you need route delegation between teams or fine-grained policies (rate limits, IP filters, and so on). The examples below write the same routing rules side by side in both styles.
Aspect
HTTPRoute (Gateway API)
HTTPProxy (Contour only)
Standard?
Official Kubernetes SIG-Network standard
A CRD of the Contour project itself
Entry point resource
A separate GatewayClass + Gateway is required
Self-contained through the virtualhost field of HTTPProxy
Delegation between teams
Cross-namespace access allowed with ReferenceGrant
Delegation per path/domain expressed explicitly with spec.includes
Fine-grained policy
Needs implementation-specific extensions (GEP) β standardization still in progress
rateLimitPolicy, ipAllow/DenyFilterPolicy, and more usable right away
Moving to another controller
Mostly reusable as-is (it is a standard)
Contour only, so it does not work on other implementations
01-gateway-api-install.shBASH
# 1) Install the Gateway API CRDs (registers GatewayClass/Gateway/HTTPRoute) β standard channelkubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml# 2) Install a Gateway Controller β Contour here as the example (Envoy Gateway, Cilium, and others can replace it)# The Contour Gateway Provisioner creates the GatewayClass "contour" automaticallykubectl apply -f https://projectcontour.io/quickstart/contour-gateway-provisioner.yamlkubectl get gatewayclass contour# Advanced topics such as per-team delegation (HTTPProxy) and policy settings continue in the# "Contour & Gateway API" section of the K8s Advanced guide (/learn/kubernetes-advanced/#contour-gateway).
02-gatewayclass-gateway.yamlYAML
# The GatewayClass is created automatically when the Provisioner manifest above is applied (for reference)apiVersion: gateway.networking.k8s.io/v1kind: GatewayClassmetadata: name: contourspec: controllerName: projectcontour.io/gateway-controller---apiVersion: gateway.networking.k8s.io/v1kind: Gatewaymetadata: name: myapp-gateway namespace: projectcontourspec: gatewayClassName: contour listeners: - name: http protocol: HTTP port: 80 allowedRoutes: namespaces: from: All - name: https protocol: HTTPS port: 443 hostname: "api.aidevops.us" tls: mode: Terminate certificateRefs: - kind: Secret name: api-aidevops-us-tls # created automatically by the cert-manager Certificate allowedRoutes: namespaces: from: All
03-httproute-app.yamlYAML
# The path routing that used to be crammed into one Ingress, managed directly by the application team in its own namespaceapiVersion: gateway.networking.k8s.io/v1kind: HTTPRoutemetadata: name: myapp-route namespace: productionspec: parentRefs: - name: myapp-gateway namespace: projectcontour hostnames: - "api.aidevops.us" rules: - matches: - path: { type: PathPrefix, value: /api/v1 } backendRefs: - name: api-service port: 8080 - matches: - path: { type: PathPrefix, value: / } backendRefs: - name: frontend-service port: 3000
03b-httpproxy-app.yamlYAML
# The same routing as the HTTPRoute just above, expressed as HTTPProxy, the Contour-specific CRD# Choose this approach on a cluster that does not use the Gateway API standard yet, or when you# need fine-grained features unique to Contour, such as includes/rateLimitPolicy.apiVersion: projectcontour.io/v1kind: HTTPProxymetadata: name: myapp-proxy namespace: productionspec: virtualhost: fqdn: api.aidevops.us tls: secretName: api-aidevops-us-tls # created automatically by the cert-manager Certificate routes: - conditions: - prefix: /api/v1 services: - name: api-service port: 8080 - conditions: - prefix: / services: - name: frontend-service port: 3000
Gateway Controller (Contour, Envoy Gateway, Cilium, and so on)
Official K8s standard, under active development
Legacy
IngressClass β Ingress
A classic Ingress Controller (e.g. ingress-nginx)
ingress-nginx reached EOL on 2026-03-24 β no new security patches
Legacy environments β if you are still using classic Ingress
Here you look at Legacy environments β if you are still using classic Ingress alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
β οΈ
The ingress-nginx project reached end of life (EOL) on March 24, 2026. Newly discovered vulnerabilities will not be patched, so if you already run ingress-nginx, planning a move to the Gateway API is recommended. With ingress2gateway (v1.0 released in March 2026), distributed by Kubernetes SIG Network, existing Ingress resources can be converted automatically into Gateway API resources (GatewayClass/Gateway/HTTPRoute).
ingress2gateway-migrate.shBASH
# Install ingress2gateway (Krew plugin or binary download)# https://github.com/kubernetes-sigs/ingress2gateway/releases# Convert the ingress-nginx based Ingresses of the current cluster to Gateway API resources and print themingress2gateway print --providers=ingress-nginx > gateway-resources.yaml# Apply after reviewing the result (existing Ingresses are not deleted automatically, so you can run both and shift traffic)kubectl apply -f gateway-resources.yaml# After verifying the switch, remove the legacy Ingresses and the ingress-nginx controller# kubectl delete ingress myapp-ingress -n production# helm uninstall ingress-nginx -n ingress-nginx
legacy-nginx-ingress.shBASH
# ββ Legacy, for reference β not recommended for new builds (ingress-nginx reached EOL on 2026-03-24) ββhelm repo add ingress-nginx https://kubernetes.github.io/ingress-nginxhelm repo updatehelm install ingress-nginx ingress-nginx/ingress-nginx \ --namespace ingress-nginx --create-namespace \ --set controller.service.type=NodePort \ --set controller.service.nodePorts.http=30080 \ --set controller.service.nodePorts.https=30443kubectl get pods -n ingress-nginx -w
legacy-ingress-app.yamlYAML
# Legacy Ingress resource β convertible to an HTTPRoute like the one above with ingress2gatewayapiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: myapp-ingress namespace: production annotations: nginx.ingress.kubernetes.io/ssl-redirect: "true" cert-manager.io/cluster-issuer: letsencrypt-prodspec: ingressClassName: nginx tls: - hosts: - api.aidevops.us secretName: api-aidevops-us-tls rules: - host: api.aidevops.us http: paths: - path: /api/v1 pathType: Prefix backend: service: name: api-service port: number: 8080 - path: / pathType: Prefix backend: service: name: frontend-service port: number: 3000
Autoscaling and high availability
Autoscaling and high availability is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
The availability strategy of Kubernetes starts not from "prevent failures from happening" but from the premise "keep the service going even when failures happen". The most basic method is to run several Pods (replicas) β if one dies, the rest take the traffic. Self-healing is added on top: the kubelet restarts a container as soon as it dies, and the kube-controller-manager keeps comparing the goal "maintain N" with the number of Pods actually alive and creates new Pods when there are too few. It is called "self-healing" because it returns to its original state without human intervention.
When traffic changes, the autoscalers step in. The HPA (Horizontal Pod Autoscaler) watches metrics such as CPU and memory and raises or lowers the number of Pods (horizontal scaling), and the VPA (Vertical Pod Autoscaler) adjusts the CPU/memory allocation of a single container (vertical scaling). If Pods stay Pending because the Nodes have no spare resources even though more Pods are wanted, the Cluster Autoscaler adds Nodes themselves to the cloud Auto Scaling Group to create real headroom. (Concrete HPA/VPA configuration examples are covered in the K8s Advanced guide.)
Concept
Role
Easy to confuse
PodDisruptionBudget (PDB)
Guarantees a minimum number of available Pods during "voluntary disruptions" such as Node drains and cluster upgrades
Cannot prevent "involuntary disruptions" such as a Node failure β for that, raise the replica count itself
Liveness Probe
Checks whether the container is alive β the kubelet restarts it on failure
Only checks that it is "up" β cannot tell whether it is ready to take traffic
Readiness Probe
Checks whether the container is ready to take traffic β on failure it is removed from the Service targets at once (no restart)
A common mistake is confusing it with Liveness and setting only Readiness where a restart is needed
Startup Probe
For apps that start slowly, holds off Liveness/Readiness judgment until the first startup completes
The fix for slow-starting JVM apps that keep getting restarted by the Liveness timeout
Setting up the monitoring stack β Prometheus & Grafana
Here you look at Setting up the monitoring stack β Prometheus & Grafana alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Observability divides into three signals β metrics (how many requests are coming in right now; numeric time series), logs (what went wrong; event text), and tracing (where is it slow; the path one request takes through several services). In Kubernetes operations, metrics are needed first. The kube-prometheus-stack Helm chart installs Prometheus (collection and storage), Grafana (visualization), Alertmanager (alerting), node-exporter (node metrics), and kube-state-metrics (metrics on the state of K8s objects) in one go.
In operation, looking at CPU/memory numbers alone is not enough. You need to check the signals peculiar to Kubernetes as well β a Pending Pod means scheduling failed (not enough resources, a node selector mismatch, and so on), CrashLoopBackOff means a container keeps dying and restarting, and OOMKilled means the kernel force-killed the process for exceeding its memory limit. These three are failure signals visible only at the K8s layer and easy to miss if you look only at application logs.
# Key Grafana dashboard IDs (grafana.com/dashboards)# In the web UI: Import β enter the ID# Overview of the whole K8s cluster# Dashboard ID: 15661 (Kubernetes / Views / Global)# Node metrics (CPU/memory/disk/network)# Dashboard ID: 1860 (Node Exporter Full)# Pod metrics (per namespace)# Dashboard ID: 6417 (Kubernetes Pods)# Spring Boot applications# Dashboard ID: 19004 (Spring Boot 3.x Statistics)# Gateway Controller (Envoy-based β Contour/Envoy Gateway and so on)# Dashboard ID: 11021 (Envoy Global), 11022 (Envoy Clusters)# If you still use legacy ingress-nginx: Dashboard ID 9614 (NGINX Ingress controller)# Alertmanager Slack integrationkubectl create secret generic alertmanager-slack \ --from-literal=slack_api_url=https://hooks.slack.com/services/XXX \ -n monitoring
Operational signal
Meaning
Common causes
Pending
The Pod has not been scheduled to any Node yet
Not enough cluster resources, no Node matching the nodeSelector/Affinity conditions, waiting for PVC binding
CrashLoopBackOff
The container keeps dying right after start and restarting
App configuration errors, failed connections to dependencies (a DB and so on), a misconfigured Liveness Probe
OOMKilled
The kernel OOM Killer force-killed the process for exceeding the memory limit
resources.limits.memory set too low, a memory leak
ImagePullBackOff
The image could not be pulled from the registry
A typo in the image tag, missing credentials for a private registry (imagePullSecrets)
Rising Restart Count
The Pod restarts more often than in normal periods
Often a Liveness Probe timeout set shorter than the response time of the app
Deployment & Service
Here you look at Deployment & Service alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A Deployment makes sure the given number of replicas is always maintained, and when a Pod dies it automatically creates a new Pod to replace it. A Service provides one fixed point of access to the group of Pods carrying the labels given in its selector, so there is no need to care about the ever-changing IPs of those Pods.
Here you look at ConfigMap & Secret alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
A Secret has almost the same API structure as a ConfigMap; the only difference is that the values are Base64-encoded. Base64 is encoding, not encryption, so anyone can recover the original with a single kubectl get secret -o jsonpath line, and a kubeadm cluster with default settings stores these values in etcd as plain text too. Do not assume it is safe just because it is called a Secret; real protection takes all the layers below together.
01-basic-usage.shBASH
# Create a ConfigMap (non-sensitive data)kubectl create configmap myapp-config \ --from-literal=DB_HOST=postgres \ --from-literal=APP_ENV=production# Create a Secretkubectl create secret generic myapp-secret \ --from-literal=DB_PASSWORD=s3cr3t# Use as environment variables in a PodenvFrom:- configMapRef: name: myapp-config- secretRef: name: myapp-secret
02-base64-is-not-encryption.shBASH
# Anyone can reverse Base64 instantly β see for yourself that it is "encoding", not "encryption"kubectl get secret myapp-secret -o jsonpath='{.data.DB_PASSWORD}' | base64 -d# β s3cr3t (anyone with permission can see the original)# Check whether etcd Encryption at Rest is enabled in the kube-apiserver manifest# (on a kubeadm cluster: /etc/kubernetes/manifests/kube-apiserver.yaml)grep -- "--encryption-provider-config" /etc/kubernetes/manifests/kube-apiserver.yaml# No output means Secrets are being stored in etcd as plain text
03-encryption-at-rest.yamlYAML
# Passed to kube-apiserver as --encryption-provider-config=/etc/kubernetes/enc/enc.yaml# (requires adding a volume/volumeMount to the static pod manifest on the Control Plane nodes)apiVersion: apiserver.config.k8s.io/v1kind: EncryptionConfigurationresources: - resources: ["secrets"] providers: - aescbc: keys: - name: key1 secret: <base64-encoded 32-byte random key> # head -c 32 /dev/urandom | base64 - identity: {} # fallback for compatibility with existing plain-text Secrets β must be last in the list---# After applying, existing Secrets must be rewritten to actually be encrypted (triggers a rewrite)# kubectl get secrets --all-namespaces -o json | kubectl replace -f -
04-rbac-secret-least-privilege.yamlYAML
# Grant only least-privilege access to Secrets, per resource name β avoid secrets read across a whole namespaceapiVersion: rbac.authorization.k8s.io/v1kind: Rolemetadata: name: myapp-secret-reader namespace: productionrules:- apiGroups: [""] resources: ["secrets"] resourceNames: ["myapp-secret"] # allow only this one Secret β other Secrets in the namespace are blocked verbs: ["get"] # list/watch not granted (blocks listing everything and watching changes)---apiVersion: rbac.authorization.k8s.io/v1kind: RoleBindingmetadata: name: myapp-secret-reader-binding namespace: productionsubjects:- kind: ServiceAccount name: myapp namespace: productionroleRef: kind: Role name: myapp-secret-reader apiGroup: rbac.authorization.k8s.io
05-external-secrets-operator.yamlYAML
# External Secrets Operator β the original exists only externally, in Vault/AWS Secrets Manager and the like,# and the K8s Secret is treated purely as a synced "copy", so the original never reaches GitapiVersion: external-secrets.io/v1beta1kind: SecretStoremetadata: name: aws-secrets-manager namespace: productionspec: provider: aws: service: SecretsManager region: us-east-1 auth: jwt: serviceAccountRef: name: myapp # a ServiceAccount linked to AWS IAM through IRSA or similar---apiVersion: external-secrets.io/v1beta1kind: ExternalSecretmetadata: name: myapp-secret namespace: productionspec: refreshInterval: 1h # re-syncs periodically β rotation is picked up automatically secretStoreRef: name: aws-secrets-manager kind: SecretStore target: name: myapp-secret # an ordinary K8s Secret is created automatically under this name data: - secretKey: DB_PASSWORD remoteRef: key: prod/myapp/db-password
Security layer
Default state
Recommended action
Base64 encoding
Anyone can decode it β not encryption
Do not assume this alone protects anything
etcd storage
Stored unencrypted by default
Enable etcd Encryption at Rest with an EncryptionConfiguration
API access control
Without RBAC, ServiceAccounts with excessive scope can read it
Grant secrets get/list in Roles minimally, per resource name; be especially careful with watch/list
Version control (Git)
Committing Secret YAML as-is is effectively plain-text exposure
Commit only in encrypted form with Sealed Secrets / SOPS; never keep the plain text in Git
Secret management system
Running the K8s Secret itself directly as the source of truth
Sync from an external store such as External Secrets Operator/Vault and manage rotation as well
Namespace strategy & resource quotas
Here you look at Namespace strategy & resource quotas alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Namespaces isolate environments (dev/staging/production), teams, and services. Set per-team resource caps with ResourceQuota and LimitRange to stop any single team from taking an excessive share of resources.
namespace-setup.shBASH
# Create a Namespace per environmentkubectl create namespace developmentkubectl create namespace stagingkubectl create namespace productionkubectl create namespace monitoringkubectl create namespace databasekubectl create namespace infra# Add labels (for NetworkPolicy and ResourceQuota selectors)kubectl label namespace production env=prod team=backendkubectl label namespace development env=dev team=backendkubectl label namespace monitoring env=infra team=ops# List the Namespaceskubectl get namespaces --show-labels
# LimitRange β default & maximum values for containers# The default values apply automatically when requests are not specifiedapiVersion: v1kind: LimitRangemetadata: name: production-limits namespace: productionspec: limits: - type: Container default: # default when requests are not specified cpu: 200m memory: 256Mi defaultRequest: cpu: 100m memory: 128Mi max: # maximum allowed per container cpu: "4" memory: 4Gi min: cpu: 50m memory: 64Mi - type: PersistentVolumeClaim max: storage: 100Gi min: storage: 1Gi
The whole deployment flow β from code to service
Here you look at The whole deployment flow β from code to service alongside real code. Rather than copying the example as-is, read it with an eye on the inputs, the outputs, and the parts most likely to change.
Let us tie every component covered so far into one story. β A developer writes code and builds an image. β‘ That image is pushed to a container registry. β’ The Deployment manifest is applied to the cluster (with kubectl apply or a GitOps tool such as ArgoCD). The API Server stores this request in etcd after authentication, authorization, and admission checks. β£ The kube-scheduler detects the newly needed Pods, picks Nodes with spare resources, and decides the placement. β€ The kubelet on that Node detects the decision and tells the container runtime to pull the image from the registry and run the container.
Practical comparisons is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
The concepts covered in this guide have similar names and are often confused in practice. When you are unsure which to choose in a given situation, use the table below for a quick refresher.
Comparison
Key difference
Pod vs Container
A Container is the unit of process execution; a Pod is the smallest K8s unit, in which Container(s) share network and volumes and are scheduled together
Deployment vs StatefulSet
In a Deployment the Pods are fully identical and interchangeable (stateless); in a StatefulSet each Pod has a unique name, network ID, and dedicated storage (stateful)
Service vs Ingress vs Gateway API
A Service is a stable endpoint at the L4 level; Ingress/Gateway API sit on top and do domain- and path-based L7 routing and TLS termination (the Gateway API is the official successor to Ingress)
ConfigMap vs Secret
Both separate configuration from code, but a ConfigMap is for non-sensitive data and a Secret for Base64-encoded sensitive data β a Secret is not encryption in itself either
NodePort vs LoadBalancer
NodePort opens a fixed port on every Node for manual exposure; LoadBalancer provisions a cloud LB automatically β in the cloud, LoadBalancer is the de facto standard
HPA vs VPA
The HPA adjusts the number of Pods (horizontal scaling); the VPA adjusts the CPU/memory allocation of one Pod (vertical scaling) β different purposes, so applying both to the same target risks conflict
Docker Compose vs Kubernetes
Docker Compose is a tool for running several containers together on a single host; Kubernetes is an orchestration platform spanning deployment, scaling, healing, and service discovery across many hosts
VM operations vs Kubernetes operations
In VM operations, people manage deployment, recovery, and scaling server by server; Kubernetes operations are declarative and automation-centered: declare only the "desired state" and the system keeps matching it
Common mistakes and operational tips
Common mistakes and operational tips is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
Below are mistakes seen again and again in practice. Knowing them in advance lets you avoid most of them.
Mistake
Why it is a problem
The right approach
Using bare Pods as production resources
They do not come back after a Node failure or deletion β with no controller there is no rescheduling at all
Always create Pods through a controller such as a Deployment/StatefulSet/Job
Depending on Pod IPs directly, with no Service
A Pod IP is a temporary address that changes on every recreation β hardcode it and the connection soon breaks
Communicate only by Service name (DNS) or ClusterIP
Believing a Secret is safe because it is Base64
Base64 is merely an encoding anyone can decode instantly, not encryption
With no basis for scheduling, resource placement becomes unbalanced, and with no limit one Pod can hog Node memory and get other Pods OOMKilled
State requests/limits on every container
Confusing Readiness and Liveness Probes
It is common to expect a restart on Readiness failure, or to set only Liveness so traffic is never cut off
Configure the roles separately: Liveness = whether to restart, Readiness = whether to receive traffic
Using a Deployment where a StatefulSet is needed
For a workload that holds data, storage attachment and network IDs get tangled on every recreation
Always use a StatefulSet for stateful workloads such as databases and message brokers
Thinking Ingress and the Ingress Controller are the same thing
People apply only the Ingress resource and are baffled that no traffic arrives β an Ingress is just a spec, not something that runs
An Ingress Controller (or Gateway Controller) must be installed separately for an Ingress to work
Confusing the CNI and Service networks
The Pod network (Pod-to-Pod communication, handled by the CNI) and the Service network (virtual IP routing, handled by kube-proxy) are different layers
When a network problem occurs, start by telling apart "is it Pod-to-Pod communication or Service routing?"
Kubernetes practical design
Kubernetes practical design is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
In Kubernetes, designing workloads, service discovery, config, secrets, and the rollout strategy matters more than writing YAML.
Decision point
Question to ask
Practical guideline
Boundaries
Which parts of the Kubernetes code are most likely to change?
Separate input/output, configuration, external integrations, and the core rules.
State
Where is state created and where does it go away?
Make the owner and lifecycle of state visible in the code.
Failure
What does the caller receive on failure?
Decide the timeout, fallback, and error contract first.
Kubernetes operating standards
This section covers Kubernetes operating standards from a practical perspective. Instead of memorizing the concept, focus on the situations in which you would reach for it.
Manage requests/limits, HPA, probes, PDBs, rollout history, and namespace quotas as operating standards.
Kubernetes verification strategy
Kubernetes verification strategy is a point where the options diverge. Using the table to compare what each approach is for and how it differs in operation makes later decisions much easier.
Include manifest validation, policy checks, canary rollouts, and rollback rehearsals.
Quality axis
How to verify
Definition of done
Correctness
Automate the normal/failure cases.
The core scenarios pass reproducibly.
Regression prevention
When fixing a bug, leave the same case behind as a test.
The same failure is not deployed again.
Operability
Check the logs, metrics, and alerts.
There is a path for tracing the cause when a problem occurs.
Kubernetes: frequently asked questions
Why do I need Kubernetes? Is Docker alone not enough?
Docker runs containers on a single server. Once containers spread across several servers, someone has to decide where each one goes, restart the ones that die, and replace old versions with new ones without interruption. Kubernetes automates this: you declare the state you want, and controllers keep the actual state matching it.
What is the difference between a Pod and a Deployment?
A Pod is the smallest unit that runs containers, and a Deployment is a higher-level object that keeps the desired number of identical Pods running and replaces them with new versions. A Pod you create directly does not come back if it is deleted or its node dies. With a Deployment, a new Pod is created automatically when one disappears, and you also get rolling updates and rollbacks. That is why real applications are almost always deployed with a Deployment.
What should I check first when a Pod is Pending, ImagePullBackOff, or CrashLoopBackOff?
Start with kubectl describe pod <name> and read the Events at the bottom. Pending usually means no node can provide the requested CPU and memory, or a PersistentVolumeClaim is not bound. ImagePullBackOff means the image name or tag is wrong, or registry credentials are missing. CrashLoopBackOff means the container exits right after starting, so check the logs of the previous run with kubectl logs <name> --previous.
How can I practice Kubernetes on my own computer?
kind, minikube, or the Kubernetes built into Docker Desktop let you practice without a cloud account. kind uses Docker containers as nodes, so it is lightweight, and a config file can create a multi-node cluster. A local cluster has no cloud load balancer, so external access is usually checked with kubectl port-forward.
Conclusion & next steps
This section covers Conclusion & next steps from a practical perspective. Instead of memorizing the concept, focus on the situations in which you would reach for it.
In the end, Kubernetes is "a distributed platform where you declare the desired state and several controllers cooperate to keep maintaining it". The Control Plane (the brain) decides and the Worker Nodes (the limbs) execute; Pods, Services, and Gateways connect the traffic; PVs/PVCs protect the data; RBAC/NetworkPolicy guard the boundaries; and the HPA/Prometheus keep watching load and state. If this picture has come together as one in your head, you are ready to dig deeper into each piece.
π
Practical summary checklist
β Is every workload created through a controller (Deployment/StatefulSet/Job)? β Are resources.requests/limits set on every container? β Are the Readiness/Liveness/Startup Probes separated according to purpose? β For Secrets, is Encryption at Rest and least-privilege RBAC applied as well, rather than trusting Base64 alone? β For a new cluster, has the Gateway API been considered as the default instead of Ingress? β Is traffic between Pods restricted to least privilege with NetworkPolicy? β Does a PodDisruptionBudget guarantee minimum availability during voluntary disruptions? β Do Prometheus/Grafana observe not only CPU and memory but also Pending/CrashLoopBackOff/OOMKilled?
π
Finished the basics?
What production operations require β HPA/VPA autoscaling, RBAC security, StatefulSet, DaemonSet, and CronJob workloads, deploying GPU-based LLM inference servers, Helm, and more β continues in the Kubernetes Advanced guide.
Topics to study next: β’ Helm β the package manager that templates and versions manifests β’ GitOps (ArgoCD / Flux) β deployment automation that treats a Git repository as the single source of truth for the desired state β’ Service Mesh (Istio / Linkerd) β adds mTLS, fine-grained traffic control, and distributed tracing with no changeto application code β’ The Operator pattern β automates the operational knowledge of a specific piece of software itself with a CRD + Controller (see the CRD section of the Prometheus guide) β’ Managed Kubernetes (EKS / AKS / GKE) β hands the burden of running the Control Plane to the cloud β’ Advanced observability β integrating logs (Loki) and tracing (Tempo/Jaeger) with metrics