Container Orchestration

• Container orchestration automates the deployment, scaling, networking, and lifecycle management of containers across multiple hosts.
• Running containers on a single host with docker run doesn’t scale: manual restart on failure, no load balancing, no rolling updates.
• Orchestrators solve this by treating the cluster as a single logical unit and continuously reconciling desired state with actual state.

Why Orchestration is Needed

Problem	Orchestration Solution
Container crashes and stays down	Auto-restart and self-healing
Traffic spike, need more instances	Horizontal autoscaling
Deploy new version without downtime	Rolling updates with health checks
Route traffic to healthy instances	Built-in load balancing
Containers on different hosts need to communicate	Overlay networking
Distributing secrets and config safely	Native secrets management

Docker Swarm

• Docker Swarm is Docker’s built-in, native clustering and orchestration solution. Enabled with a single command.
• Simpler than Kubernetes, but significantly less powerful. Good for teams already comfortable with Docker who need basic multi-host orchestration.

Swarm Concepts

• Node: A Docker host in the swarm. Either a manager (hosts control plane, schedules tasks) or a worker (runs containers).
• Service: A definition of a task to run on the swarm - similar to docker run but orchestrated across the cluster.
• Task: A single container instance of a service. Swarm maintains the desired number of tasks across healthy nodes.
• Stack: A group of services defined in a Compose file and deployed together (docker stack deploy).

Caution

build: is silently ignored in Swarm mode. docker stack deploy does not build images — it only pulls them from a registry. Always push your images to a registry before deploying a stack, and use the image: key instead of build: in your Compose file.

Setting Up a Swarm Cluster

# On the manager node - initialize the swarm
docker swarm init --advertise-addr <manager-ip>
# Output includes a join token for workers

# On each worker node - join the swarm
docker swarm join --token SWMTKN-1-xxx <manager-ip>:2377

# Verify the cluster
docker node ls

Running Services on Swarm

# Deploy a service with 3 replicas across the cluster
docker service create --name web --replicas 3 -p 80:80 nginx

# List services
docker service ls

# See which nodes are running which tasks
docker service ps web

# Scale up/down
docker service scale web=5

# Rolling update to a new image
docker service update --image nginx:1.26 web

# Remove a service
docker service rm web

# Deploy an entire Compose stack
docker stack deploy -c docker-compose.yml myapp

# List stacks
docker stack ls

# View services in a stack
docker stack services myapp

Kubernetes

• Kubernetes (K8s) is the industry-standard container orchestration platform, originally developed by Google, now maintained by the CNCF.
• Significantly more powerful and complex than Swarm. Designed for large-scale production deployments with sophisticated requirements.
• Supports multiple container runtimes (containerd, CRI-O) - not limited to Docker images, but OCI images built with Docker work natively.

Note

Kubernetes does not use Docker as its runtime (since K8s v1.24, dockershim was removed). It uses containerd or CRI-O directly. OCI images you build with docker build work without modification — the image format is standardized. The section below is an orientation to K8s concepts, not a full reference.

Core Objects

Object	Purpose
Pod	Smallest deployable unit. One or more containers sharing network and storage.
Deployment	Manages rolling updates and rollbacks for a set of replica Pods.
Service	Stable network endpoint for a set of Pods. Enables load balancing and service discovery.
ConfigMap	Store non-sensitive configuration data consumed by Pods as env vars or files.
Secret	Base64-encoded sensitive data (passwords, tokens). Encrypted at rest in etcd.
PersistentVolume (PV)	A piece of storage provisioned by an admin or dynamically by a StorageClass.
Namespace	Virtual cluster within a cluster. Used for multi-tenancy and resource isolation.
Ingress	HTTP/HTTPS routing rules - exposes services to external traffic with URL-based routing.

Kubernetes Architecture

Control Plane (Master):

• kube-apiserver - all K8s API requests go through here. Single source of truth.
• etcd - distributed key-value store holding all cluster state.
• kube-scheduler - selects which node a Pod runs on based on resource requirements and constraints.
• kube-controller-manager - runs controllers that reconcile actual state toward desired state (e.g., ensures Deployments have the right number of replicas).

Worker Nodes:

• kubelet - agent on each node. Receives Pod specs and ensures containers are running as specified.
• kube-proxy - manages iptables/IPVS rules for Service networking on each node.
• Container Runtime - containerd or CRI-O. Pulls images and starts/stops containers.

Swarm vs Kubernetes

Dimension	Docker Swarm	Kubernetes
Setup complexity	Low - one command	High - many components
Learning curve	Low	High
Scale	Thousands of containers	Tens of thousands of nodes
Auto-scaling	Manual only	HPA / KEDA (automatic)
Rolling updates	Basic	Fine-grained (canary, blue/green)
Networking	Overlay (built-in)	Plugin-based (Calico, Cilium, etc.)
Storage	Basic volume support	Rich CSI driver ecosystem
Community	Small, mostly Docker Inc	Massive CNCF ecosystem
Managed Cloud Options	None mainstream	AKS, EKS, GKE

When to use Swarm: Small teams, simple microservices, already deep in Docker Compose tooling, don’t need the Kubernetes ecosystem.

When to use Kubernetes: Production at scale, need horizontal pod autoscaling, want access to the CNCF ecosystem (Helm, ArgoCD, Istio, etc.), deploying to a managed cloud (AKS/EKS/GKE removes most of the operational burden).

[!note] For most new production workloads: use a managed Kubernetes service (AKS, EKS, GKE). The control plane is free, managed, and upgraded for you. The operational complexity concern with K8s largely disappears with managed offerings.