Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Operating Microservices

Containers, Docker Compose and Kubernetes

Package each microservice in a container, run a local system with Docker Compose, and let Kubernetes schedule, heal and expose services with probes.

Dozens of services, each in its own language and with its own dependencies, are hard to run by hand. Containers solve the packaging half of that problem: a container image holds one service together with exactly what it needs, and runs the same way on a laptop, in CI and in production. Orchestration solves the other half: deciding where containers run, restarting them when they die, and wiring them together.

This lesson shows how the pieces fit a microservice architecture: one service, one container, Docker Compose for running the whole system locally, and Kubernetes for production. The real tools need a Docker daemon or a cluster, which this site cannot provide, so their files here are read-only. The two runnable stand-ins show how an orchestrator thinks: a scheduler placing containers on machines, and health probes deciding when to restart or route traffic. Deeper coverage lives in the Docker and Kubernetes tutorials; this lesson stays at the microservices level.

From code to running system

Image One service plus its dependencies.
Compose Run many containers on one machine.
Kubernetes Run many containers on many machines.
1 / 2

One service, one container

Container boundaries line up nicely with service boundaries. Each service gets its own image, built from its own repository or folder, started with its own configuration and scaled on its own. A few habits make images good citizens of a microservice system:

  • One main process per container (the service itself), logging to standard output so the platform can collect logs.
  • Small, reproducible images, usually with a multi-stage build (see Multi-Stage Builds), a pinned base image and a non-root user.
  • Configuration from the environment, not baked into the image, so the same image runs in every stage (more in Configuration, Feature Flags and Secrets).
  • No state inside the container. Containers are disposable: anything that must survive goes to a database, a volume or object storage (data ownership says which service owns it).
  • A health endpoint such as /healthz that tells the platform whether the service works.

A typical Dockerfile for a small Node.js service (read-only; see Dockerfile Basics to learn each instruction):

DOCKERFILE
FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .

FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app /app
USER node
EXPOSE 3000
CMD ["node", "server.js"]

Docker Compose: the whole system on a laptop

Developers need to start the system locally without installing a dozen databases. Docker Compose describes several containers in one YAML file and starts them together on one machine, with a private network where services reach each other by service name. It is ideal for local development and for integration tests in CI, and acceptable for small single-host deployments. See Compose Introduction for the full tool.

YAML
services:
  orders:
    build: ./orders
    ports:
      - "8080:3000"
    environment:
      DATABASE_URL: postgres://orders:secret@orders-db:5432/orders
      PAYMENTS_URL: http://payments:3000
    depends_on:
      orders-db:
        condition: service_healthy

  payments:
    build: ./payments
    environment:
      BROKER_URL: amqp://broker:5672

  orders-db:
    image: postgres:17
    environment:
      POSTGRES_USER: orders
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: orders
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U orders"]
      interval: 5s
      retries: 5
    volumes:
      - orders-data:/var/lib/postgresql/data

  broker:
    image: rabbitmq:4-management

volumes:
  orders-data:

Notice that orders talks to http://payments:3000 and orders-db: Compose gives each service a DNS name. Notice also the database belongs to one service only, following the "database per service" rule. The password shown is a local-development value; never commit real secrets.

Compose does not spread containers over several machines, does not roll out updates gradually and does not self-heal in a meaningful way. For that, production systems use an orchestrator.

Kubernetes in one page

Kubernetes (K8s) is a cluster of machines (nodes) plus a control plane. You describe the desired state in YAML ("run 3 copies of this image, reachable under this name") and Kubernetes continuously works to make reality match, which is called a reconciliation loop. The important objects for a microservice are:

  • Pod: the smallest unit, one or more containers that share a network address. Pods are disposable.
  • Deployment: keeps N identical pods running and replaces them gradually when you change the image (a rolling update, see Deployment Strategies and CI/CD). Pods that die are replaced.
  • Service: a stable name and virtual IP in front of a changing set of pods, with load balancing. This is the platform's answer to service discovery.
  • Ingress / Gateway: routes outside traffic to services (see API Gateway).
  • ConfigMap and Secret: configuration and sensitive values injected as environment variables or files.
  • Probes: how Kubernetes checks health, described below.

This is a real (read-only) manifest for the orders service: a Deployment with three replicas, resource requests and limits, and probes, plus a Service in front of it.

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders
spec:
  replicas: 3
  selector:
    matchLabels:
      app: orders
  template:
    metadata:
      labels:
        app: orders
    spec:
      containers:
        - name: orders
          image: registry.example.com/shop/orders:1.4.2
          ports:
            - containerPort: 3000
          env:
            - name: PAYMENTS_URL
              value: http://payments
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              memory: 512Mi
          readinessProbe:
            httpGet:
              path: /ready
              port: 3000
            periodSeconds: 5
          livenessProbe:
            httpGet:
              path: /healthz
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: orders
spec:
  selector:
    app: orders
  ports:
    - port: 80
      targetPort: 3000

Other services in the same namespace now reach it as http://orders. The requests values tell the scheduler how much room the pod needs; the limits cap what it may use. Read more in Deployments, Services and Resource Requests and Limits.

How a scheduler places pods

When you create a pod, Kubernetes must choose a node. The scheduler first filters out nodes that cannot take the pod (not enough free CPU or memory), then scores the rest and picks the best, for example the node with the most free resources, which spreads load. If no node fits, the pod stays Pending. If a node dies, its pods are rescheduled elsewhere.

The real scheduler has many more rules (affinity, taints, topology spread; see The Scheduler). The stand-in below keeps the two main ideas, filter and score, and then simulates a node failure.

JS A tiny scheduler: filter, score, reschedule

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the output to see the two effects. First, pods spread over the nodes instead of piling onto one. Second, after the failure the surviving nodes are too small to hold everything, so some pods stay Pending: capacity planning matters, and clusters usually keep spare room (or use an autoscaler that adds nodes). The system declared "I want these pods" and kept trying to satisfy it.

Probes: health, restarts and traffic

Kubernetes asks each container two different questions, and mixing them up is a common mistake.

  • Liveness: "Is the process still working, or is it stuck?" If the check fails repeatedly, Kubernetes restarts the container. Keep it cheap and independent of other services; a liveness probe that checks the database will restart healthy pods whenever the database is down.
  • Readiness: "Can you take traffic right now?" If it fails, the pod is removed from the Service's endpoints (no restart), and it comes back automatically when the check passes. Use it for slow startup, warming caches and temporary overload.
  • Startup probes give slow-starting applications extra time before the other two begin.
JS Readiness and liveness probes over time

Press Run (or Ctrl + Enter) to see the console output here.

No output.

During startup and the two overloaded seconds the pod was not ready, so users were not sent to it, yet it was not restarted. When it hung completely, liveness failed twice in a row and the container was restarted, after which it went through startup again. Readiness protects users; liveness repairs the process.

Is Kubernetes always the answer?

No. Kubernetes is a powerful platform with a real learning and operating cost. For a handful of services, a managed container platform (cloud "run this container" services) or Compose on a single server may be simpler. Many teams use a managed Kubernetes service so someone else runs the control plane. Whatever you choose, the principles are the same: immutable images, declarative desired state, health checks, resource requests, and stateless services that can be killed and replaced at any time.

An orchestrator keeps containers running, not correct. It will happily restart a service that fails in a loop. Pair it with the resilience patterns from this chapter and the observability tools to learn about problems before your users do.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does a container image suit microservices?

    An image is a portable, reproducible package, which matches the idea of independently deployed services.
  2. 2. What is Docker Compose mainly used for?

    Compose defines a multi-container application in one file and runs it on a single host.
  3. 3. What does a Kubernetes Service provide?

    Pods come and go with changing addresses. The Service gives callers one stable endpoint.
  4. 4. What happens when a readiness probe fails?

    Readiness controls traffic only. Restarts are the job of the liveness probe.
  5. 5. A pod stays Pending after a node failure. What is the most likely reason?

    The scheduler filters out nodes without room. Without capacity (or an autoscaler), the pod waits.

Summary

  • Give each microservice its own container image: one main process, small and reproducible, configured from the environment and stateless.
  • Docker Compose runs a multi-container system on one machine for development and tests; services reach each other by name.
  • Kubernetes keeps the declared state: Deployments maintain replicas, Services give stable names, and a scheduler places pods using their resource requests.
  • Liveness probes restart stuck containers; readiness probes decide whether a pod receives traffic.
  • Choose the simplest platform that meets your needs, and combine it with resilience and observability practices.

Next: Configuration, Feature Flags and Secrets.