Web servers
through the F1 lens.

Stage 01 role of the web server

What a web server is for

The problem

The concept

A web server is the point through which every HTTP request enters before reaching (or not) the application. The application, also called the backend or application server (Node.js, PHP-FPM, Tomcat, Gunicorn), runs the business logic. The web server takes care of everything around it. A modern web server typically takes on six functions:

• Serve static content: it delivers HTML, CSS, JavaScript, images and videos straight from disk, without invoking application code.
• Proxy to dynamic applications: it forwards requests to PHP-FPM, Tomcat, Node.js, Gunicorn and similar.
• Balance load: it distributes requests among several application servers.
• Terminate TLS: it manages certificates and encryption at a central point, instead of spreading that task across each instance.
• Cache: it stores responses already produced to deliver them faster later, without repeating the work.
• Control access and security: it filters malicious traffic and applies authentication before the attack gets near the application.

Apache HTTP Server had its first release in 1995, so the category has more than three decades of use. When the web server answers before any application exists (for example, a 404 for a nonexistent file), it shows that it is a layer of its own, and the Server header of the response identifies which software answered. The following stages go deeper into each function: proxy in Stage 03, Apache's MPMs in Stage 04, Nginx's architecture in Stage 05 and balancing in Stage 06.

Key concepts

A minimal web server and the Server header

# default.conf
server {
    listen 80;                       # the port Nginx listens on
    server_name localhost;           # the name this block serves
 
    location / {                     # rule for all URLs that start with "/"
        root /usr/share/nginx/html;  # the folder where the static files are
        index index.html;            # file served when the URL ends in "/"
    }
}

Essential commands for this stage

Hands-on

1. Start both containers: docker run -d --name nginx-lab -p 8080:80 nginx:stable and docker run -d --name apache-lab -p 8081:80 httpd:2.4.
2. Run curl -I http://localhost:8080 and curl -I http://localhost:8081. Observe the Server header of each one and the 200 OK.
3. Ask for a path that does not exist (curl -I http://localhost:8080/nao-existe) and observe the 404 Not Found. That response came from the web server, with no application having been invoked.
4. Run docker logs nginx-lab and observe the access lines with your requests, including the one that resulted in a 404.
5. Clean up: docker rm -f nginx-lab apache-lab.

Stage 02 protocol evolution

HTTP and its evolution, from 1.1 to HTTP/3

The problem

The concept

Before the versions, a structural fact: HTTP is a stateless protocol. Each request is handled independently, with no memory of the previous ones. This simplifies scaling, but requires mechanisms on top of the protocol (cookies and sessions) to keep the context of the same user.

• HTTP/1.1 (1997): it introduced persistent connections (keep-alive), allowing several requests and responses on the same TCP connection and reducing the cost of opening a new connection per resource. The limitation is head-of-line blocking: if the first request is slow, the following ones on the same connection wait.
• HTTP/2 (2015): it solves the head-of-line blocking of the first scene, at the application layer. Several requests and responses (streams) travel at the same time over the same TCP connection, with none blocking another. It also brought resource prioritization, header compression (HPACK) and Server Push, which fell out of use because the main browsers removed or restricted support, since the gain rarely justified the complexity. On the web, HTTP/2 is used over TLS, and client and server agree on the version during the TLS handshake (ALPN extension).
• HTTP/3 (QUIC over UDP): HTTP/2 solved the problem in the application, but TCP guarantees that bytes arrive in strict order. If a packet is lost, everything that came after it waits for the retransmission, even if it belongs to another stream. HTTP/3 replaces TCP with QUIC, which runs over UDP: each stream is independent, and the loss of a packet only delays the affected stream. QUIC also combines the transport handshake with the TLS 1.3 one, which tends to establish the connection faster. The gain is larger on networks with packet loss or high latency, such as mobile connections.

In practice, the client discovers that the server offers HTTP/3 through the Alt-Svc response header. Networks that block UDP on port 443 make the client fall back to HTTP/2 or HTTP/1.1.

HTTP/2: the red and green streams share the same TCP connection. If one link is lost, everything after it waits for the retransmission, whichever stream it belongs to.

HTTP/3: in QUIC, each stream is an independent chain, and losing a link only delays the chain it was in.

Key concepts

Asking curl which version was negotiated

# Lets curl negotiate freely and shows the version used (approximate output)
$ curl -so /dev/null -w 'Protocolo negociado: HTTP/%{http_version}\n' https://www.cloudflare.com
Protocolo negociado: HTTP/2
 
# Forces HTTP/1.1, even if the server supports newer versions
$ curl --http1.1 -so /dev/null -w 'Protocolo negociado: HTTP/%{http_version}\n' https://www.cloudflare.com
Protocolo negociado: HTTP/1.1
 
# Forces HTTP/3 (requires a curl built with QUIC support)
$ curl --http3 -so /dev/null -w 'Protocolo negociado: HTTP/%{http_version}\n' https://www.cloudflare.com
Protocolo negociado: HTTP/3

Essential commands for this stage

Hands-on

1. Choose a domain that supports HTTP/2 (for example, www.cloudflare.com) and run the first two commands of the example. Observe the value of %{http_version} changing according to the flag.
2. Run curl -v --http2 https://www.cloudflare.com 2>&1 | grep -i "HTTP/2" and observe the line that confirms the version negotiated in the handshake.
3. If your curl supports HTTP/3, repeat with --http3 and compare -w '%{time_total}\n' across the three variants. Do not expect a large difference on a stable network.
4. Generate the certificate, create h2.conf and start h2-lab. Observe HTTP/2 on the first call and HTTP/1.1 with --http1.1.
5. Delete the http2 on; line from the local h2.conf and run docker exec h2-lab nginx -s reload. Repeat the curl with no flag and observe that the version goes back to HTTP/1.1, because the server stopped offering h2 in the handshake. Warning: the file is mounted individually in the container, and some editors and sed -i replace the file with a new one instead of changing the original. In that case the container keeps seeing the old version and the reload seems to do nothing; run docker restart h2-lab and repeat the test.
6. Clean up: docker rm -f h2-lab.

Stage 03 intermediaries

Forward proxy and reverse proxy

The problem

The concept

Forward proxy, the outbound intermediary. It sits between a client (usually on a private network) and the internet, and is configured explicitly on the client side (browser, operating system or application). The flow is this: the client sends the request to the proxy indicating the destination; the proxy analyzes it and decides whether to forward or block it; if it forwards, it makes the request on the client's behalf; the response returns to the proxy, which passes it on to the client. For HTTPS, the client asks the proxy for a tunnel (the CONNECT method), and the proxy only sees the content if it does TLS inspection. Use cases: security and compliance, content control, anonymity (masking the client's IP) and cache. Squid is an example of software that fills this role.

Reverse proxy, the inbound intermediary. It sits at the edge of the infrastructure, receives requests from the internet and distributes them to the application servers behind it. It is transparent to the client, who does not even know it exists. The flow: the client sends the request to the proxy's public IP; based on rules, the proxy chooses the backend; it forwards the request; the backend answers the proxy; the proxy delivers the response to the client. Main functions: load balancing, centralized TLS termination (taking that load off the backends), cache, a first layer of security, compression (Gzip or Brotli) and routing between services. On security, the plain proxy filters certain traffic patterns, but blocking attacks such as XSS normally requires WAF rules (Stage 14).

The practical rule to tell the two apart: ask who configured the pointing to the intermediary. If it was the client, it is a forward proxy. If it was the server's infrastructure and the client does not know, it is a reverse proxy.

There is a consequence for the backend: it only sees the proxy opening the connection. To know who really made the request, the proxy passes on the client's IP in headers such as X-Real-IP and X-Forwarded-For (not standardized, but widely used; the standardized header is Forwarded). The backend should only trust these headers when they come from a known proxy, because a client can send them forged.

Forward proxy: the proxy sits on the client's network, and the client uses it to reach the outside. The external site only sees the proxy.

Reverse proxy: the proxy sits on the server's network, and whoever comes from the internet talks only to it, without knowing which server answered.

Key concepts

Nginx reverse proxy and Squid forward proxy in the same lab

# backend.py
import os
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 
NAME = os.environ.get("NAME", "backend")      # name returned in the responses
PORT = int(os.environ.get("PORT", "3000"))    # listening port
DELAY = float(os.environ.get("DELAY", "0"))   # artificial delay, in seconds
 
 
class Handler(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"             # allows persistent connections
 
    def responder(self, com_corpo):
        if self.path == "/slow":
            time.sleep(10)                    # simulates a stuck backend
        elif self.path != "/healthz":
            time.sleep(DELAY)                 # simulates a slow backend
        if self.path.endswith("/headers"):
            linhas = [f"peer: {self.client_address[0]}"]   # who opened the TCP connection
            linhas += [f"{k}: {v}" for k, v in self.headers.items()]
            corpo = "\n".join(linhas) + "\n"
        else:
            corpo = f"{NAME} recebeu {self.path}\n"
        dados = corpo.encode()
        self.send_response(200)
        self.send_header("Content-Length", str(len(dados)))
        self.end_headers()
        if com_corpo:                         # HEAD does not send a body
            self.wfile.write(dados)
 
    def do_GET(self):
        self.responder(True)
 
    def do_HEAD(self):
        self.responder(False)
 
 
ThreadingHTTPServer(("0.0.0.0", PORT), Handler).serve_forever()

Essential commands for this stage

Hands-on

1. Create the etapa03/ folder with backend.py, nginx.conf, squid.conf and compose.yaml, and run docker compose up -d. Confirm the three services with docker compose ps.
2. Run curl -s http://localhost:8080/headers and observe X-Real-IP, X-Forwarded-For and Host: localhost. Then run curl -sI http://localhost:8080/ and observe Server: nginx, even with the content coming from Python.
3. Delete the proxy_set_header Host $host; line from nginx.conf, run docker compose exec nginx nginx -s reload and repeat /headers. Observe Host: backend_app, the name of the upstream, instead of the domain the client asked for. Warning: nginx.conf is mounted as a single file, and some editors and sed -i replace it with a new file, which leaves the container seeing the old version. If the change does not show up after the reload, run docker compose restart nginx.
4. Restore the line, delete proxy_set_header X-Real-IP $remote_addr;, reload and repeat. Observe that X-Real-IP disappears, but X-Forwarded-For still carries the client's IP, and that peer shows Nginx's IP (the peer was always Nginx, because it is the one that opens the connection to the backend). Also delete the X-Forwarded-For line, reload and repeat: without both headers, the backend only sees Nginx.
5. Restore the lines and run curl -s -x http://localhost:3128 http://backend:3000/headers. Observe the Via and X-Forwarded-For headers added by Squid. Compare with curl -s http://backend:3000/, which fails to resolve the name.
6. Clean up: docker compose down.

Stage 04 processes + threads

Apache HTTP Server and the processing models (MPMs)

The problem

The concept

Before the models, two terms. A process has its own memory, isolated from the others; if it fails, the others carry on. A thread lives inside a process and shares its memory with the other threads, which makes it lighter and more dangerous: a serious error in one thread can corrupt the whole process. Code that works correctly when several threads run it at the same time is called thread-safe.

• Prefork (no threads): an independent child process serves each connection, completely isolated from the others. Advantages: very stable (a problem in one process does not affect the others), compatible with non-thread-safe modules and with legacy software. Disadvantages: high memory consumption and poor scalability under high concurrency. It is common to see Prefork with mod_php (PHP embedded in the Apache process, historically not thread-safe). The alternative is to run PHP as a separate process, PHP-FPM, with Apache talking to it through a proxy (mod_proxy_fcgi, the same concept as Stage 03), which allows using a lighter MPM without losing compatibility.
• Worker (with threads): it creates several child processes, each with several threads, and each thread serves one connection. It uses less memory than Prefork and supports more concurrency. Since the threads of a process share memory, a serious error in one of them can bring down the child process that hosts it and the connections it was serving; the other children and the master process stay up. That is why modules need to be thread-safe.
• Event (recommended for most new deployments): it starts from Worker, but is optimized for the common case of open, idle keep-alive connections. A dedicated thread can watch several connections that are only waiting, without tying a worker thread to each idle connection. It keeps the requirement of thread-safe modules and is the MPM recommended for HTTP/2, which Apache offers through the mod_http2 module (enabled with a2enmod http2 and Protocols h2 http/1.1).

Two reading points for the comparison: memory consumption grows in the order Event, Worker, Prefork, and the supported concurrency grows in the opposite order. The choice, therefore, is always a trade between isolation and efficiency.

Key concepts

Finding and switching the active MPM

# Shows the MPM in use (shortened output)
$ apachectl -V | grep -i mpm
Server MPM:     event
 
# On Debian and Ubuntu, a2query shows the enabled MPM module
$ sudo a2query -M
event
 
# Switches to Prefork (for example, to run a legacy non-thread-safe module)
$ sudo a2dismod mpm_event      # disables the current MPM
$ sudo a2enmod mpm_prefork     # enables Prefork
$ sudo systemctl restart apache2
 
$ sudo a2query -M
prefork

Essential commands for this stage

Hands-on

1. Create the etapa04/ folder with the Dockerfile above, build the two images and start the two containers as in the example.
2. Confirm each one's MPM with docker exec <container> httpd -M | grep mpm. Observe mpm_event_module and mpm_prefork_module.
3. In one terminal, run ab -n 50000 -c 100 http://localhost:8082/ (Prefork). In another, run docker top apache-prefork | grep -c httpd several times during the test and observe the number of processes grow.
4. Repeat step 3 against http://localhost:8081/ (Event) and apache-event. Observe that the number of processes stays small, because each process holds several threads. Also compare docker stats --no-stream apache-event apache-prefork at the end of the tests. The exact numbers vary; what matters is the difference in order of magnitude in the processes.
5. If you have an Apache installed on the host (sudo apt install apache2), switch the MPM with a2dismod and a2enmod, restart the service and confirm with sudo a2query -M.
6. Clean up: docker rm -f apache-event apache-prefork. The apache-event and apache-prefork images stay on the computer and can be reused in Stage 05.

Stage 05 event loop

Nginx and the event-driven architecture

The problem

The concept

The central difference is the asynchronous, event-driven architecture, instead of a dedicated process or thread per connection.

A master process reads the configuration and manages the worker processes, which are the ones that serve connections (the master does not serve requests). Each worker runs an event loop: a loop that waits for events (new data on a connection, a response from a backend, a write becoming available), handles what became ready and goes back to the loop. When an input and output operation would have to wait (reading from disk, waiting for a backend), the worker does not stand still: it registers interest in that event and moves on to handle another connection. This is non-blocking I/O. When the event becomes ready, the worker is notified and resumes exactly where it stopped.

On Linux, the notification of which connections have new data comes from a kernel mechanism, epoll, which avoids scanning all connections on every cycle. Nginx picks the most efficient method available on its own, so the use epoll; directive is usually optional on Linux.

The practical result is that the number of processes stays stable and small (usually one worker per CPU core), while the number of connections grows. The limit stops being "one thread per connection" and becomes CPU, memory and file descriptors. Benefits: lower memory consumption, higher throughput, good latency and excellent performance as a reverse proxy and balancer, including in front of Apache itself. Be careful with the capacity calculation: worker_processes times worker_connections is the ceiling of simultaneous connections, but, when Nginx acts as a proxy, each client request uses two connections (one with the client and one with the backend), so the number of simultaneous clients is about half of that ceiling. In addition, worker_connections must not exceed the process's open file limit (adjustable with worker_rlimit_nofile).

Key concepts

Few processes, many connections

# nginx.conf (main excerpt)
worker_processes auto;          # one worker process per available CPU core
 
events {
    worker_connections 1024;    # each worker accepts up to 1024 simultaneous connections
    use epoll;                  # optional on Linux: Nginx already picks the most efficient method
}

Essential commands for this stage

Hands-on

1. Start the test Nginx with docker run -d --name nginx-lab -p 8080:80 nginx:stable and run docker exec nginx-lab nginx -T | grep -E 'worker_processes|worker_connections'. Observe worker_processes auto and worker_connections 1024.
2. Run docker top nginx-lab and count the worker processes. Compare with nproc: the number of workers is usually equal or close to the number of cores (the container sees the host's cores).
3. Run ab -n 50000 -c 200 http://localhost:8080/ and, during the test, repeat docker top nginx-lab in another terminal. Observe that the number of processes does not change, even with 200 simultaneous connections.
4. The apache-prefork container was deleted at the end of Stage 04, so recreate it with docker run -d --name apache-prefork -p 8082:80 apache-prefork (the image is still on the computer; if you removed it, rebuild it with docker build --build-arg MPM=prefork -t apache-prefork . in the etapa04/ folder). Repeat the load on http://localhost:8082/ and run docker top apache-prefork | grep -c httpd. Observe the number of processes grow along with the load, unlike what happened with Nginx.
5. Compare memory consumption with docker stats --no-stream nginx-lab apache-prefork.
6. Optional, on an Nginx installed on the host (sudo apt install nginx): run nginx -t and ps aux | grep '[n]ginx' and repeat steps 2 and 3 against http://localhost/.
7. Clean up: docker rm -f nginx-lab apache-prefork.

Stage 06 L4 + L7 + algorithms

Load balancing: L4, L7 and Nginx algorithms

The problem

The concept

A load balancer distributes requests among the backends. The decision can use little or a lot of information, and that defines the layer it works at.

• L4 (transport): it decides with IP and port, over TCP or UDP. It is fast, serves generic protocols (databases, for example), but cannot route by URL, host or header because it does not even read HTTP. In Nginx, this is done by the stream module.
• L7 (application): it understands HTTP and HTTPS. It can terminate TLS, apply cache and compression and route by host, path, header or cookie, with a slightly higher overhead.

In Nginx, the algorithms of the upstream block are:

• Round Robin: the default; it distributes in sequence. The weight parameter changes the proportion for servers with different capacities (weight=2 receives double).
• least_conn: it sends the request to the backend with the fewest active connections. It is suitable when requests have very different durations.
• ip_hash: the same client tends to always land on the same backend, based on the IPv4 address (it uses the first three octets) or the IPv6 address (the whole thing). It helps applications with local state, but concentrates many users behind the same NAT or VPN on a single backend.

Affinity like that of ip_hash makes redistribution and scalability harder. Whenever possible, prefer stateless applications: session in Redis or a signed token (such as JWT) allow any backend to answer any request. Two directives complete the picture: keepalive reuses connections between Nginx and the backends (it requires proxy_http_version 1.1 and proxy_set_header Connection ""), and the timeouts proxy_connect_timeout, proxy_send_timeout and proxy_read_timeout limit each phase of the conversation with the upstream.

Key concepts

An upstream with an explicit decision

 # compose.yaml
x-backend: &backend                        # template reused by both backends
  image: python:3.12-alpine
  command: ["python", "/app/backend.py"]   # runs the didactic backend
  volumes:
    - ./backend.py:/app/backend.py:ro      # mounts the script read-only
 
services:
  api-1:
    <<: *backend                           # inherits the template above
    environment:
      NAME: api-1                          # name returned in the responses
      DELAY: "${API1_DELAY:-0}"            # delay configurable by environment variable (default 0)
  api-2:
    <<: *backend
    environment:
      NAME: api-2
  nginx:                                   # L7 balancer (HTTP)
    image: nginx:stable
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - api-1
      - api-2
  nginx-l4:                                # L4 balancer (plain TCP)
    image: nginx:stable
    ports:
      - "9090:9090"
    volumes:
      - ./nginx-l4.conf:/etc/nginx/nginx.conf:ro   # replaces the whole nginx.conf
    depends_on:
      - api-1
      - api-2

Essential commands for this stage

Hands-on

1. Create etapa06/ with backend.py, compose.yaml, nginx.conf and nginx-l4.conf, and run docker compose up -d.
2. With Round Robin, run for i in $(seq 1 30); do curl -s http://localhost:8080/api/; done | sort | uniq -c. Observe a split of 15 to 15.
3. Add weight=2 to api-1, validate and reload (docker compose exec nginx nginx -t and then nginx -s reload) and repeat the count. Observe about 20 for api-1 and 10 for api-2. If the split does not change, the container may be seeing the old version of the file (editors and sed -i replace the mounted file with a new one); run docker compose restart nginx and repeat the count.
4. Remove the weight, enable least_conn;, reload and run API1_DELAY=1 docker compose up -d api-1. Reload Nginx again (the IP of api-1 may have changed) and run seq 1 20 | xargs -P 10 -I{} curl -s http://localhost:8080/api/ | sort | uniq -c. Observe that the slow backend receives less new work (for example, 5 against 15; the numbers vary).
5. Replace least_conn; with ip_hash;, reload and repeat the count. Observe that all responses come from the same backend. Explain why: because of Docker's port mapping, all requests reach Nginx with the same source IP (that of the network gateway). It is the effect of many users behind the same NAT.
6. Compare L4 and L7: run curl -s http://localhost:8080/ and curl -s http://localhost:9090/. Observe that only L7 answers on its own for a route, because only it reads the path.
7. Measure with ab -n 1000 -c 20 -k http://localhost:8080/api/ and note Requests per second and the mean time per request. Then describe in one sentence how Redis or JWT would eliminate the need for ip_hash.
8. Clean up: docker compose down.

Stage 07 health checks + 502/504

Health checks, failover, metrics and diagnosis

The problem

The concept

Health checks. In Nginx Open Source, the max_fails and fail_timeout parameters implement passive checking: failures observed in real requests temporarily take the backend out of rotation. With max_fails=3 fail_timeout=10s, three failures within 10 seconds take the server out of rotation for 10 seconds; after that Nginx tries it again and puts it back if the call works. Passive checking depends on real traffic: with no requests, there are no failures to observe. Active checks (periodic probes independent of traffic, with the health_check directive) are a feature of Nginx Plus, the commercial edition, or of external modules. A detail: in a group with a single server, max_fails and fail_timeout are ignored.

Failover and backup. When an attempt fails by connection error or timeout, Nginx tries the next server in the group (the default behavior of proxy_next_upstream), so the client does not always notice the failure. The backup parameter reserves a server that only receives requests when all the primaries are unavailable (it cannot be combined with ip_hash, hash or random).

Metrics. The stub_status module exposes active connections, total connections and accepted requests, and the reading, writing and waiting states. Apache Bench (ab) generates controlled load. Read together requests per second, latency, percentiles (the p95 shows the experience of the slowest ones, which the average hides), CPU and logs, to know whether the limit is in the proxy, in the backend or in a dependency.

Diagnosing 502 and 504. The 502 Bad Gateway error indicates that Nginx did not obtain a valid response from the upstream: connection refused, connection closed or invalid response. The 504 Gateway Timeout error indicates that the connection was made, but the backend did not answer within proxy_read_timeout. The investigation follows the path of the request: client, Nginx, backend, dependencies. Increasing a timeout without investigating may only hide slowness.

Key concepts

Primary and backup backends, status panel and provoked errors

 # compose.yaml
x-backend: &backend
  image: python:3.12-alpine
  command: ["python", "/app/backend.py"]
  volumes:
    - ./backend.py:/app/backend.py:ro
  networks: [lab]
 
services:
  api-1:
    <<: *backend
    environment: { NAME: api-1 }
  api-2:
    <<: *backend
    environment: { NAME: api-2 }
  api-backup:
    <<: *backend
    environment: { NAME: api-backup }      # only answers when the primaries fail
  nginx:
    image: nginx:stable
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    networks: [lab]
    depends_on: [api-1, api-2, api-backup]
  tools:                                   # container only to run curl inside the network
    image: curlimages/curl
    entrypoint: ["tail", "-f", "/dev/null"]
    networks: [lab]
 
networks:
  lab:
    ipam:
      config:
        - subnet: 172.30.0.0/24            # fixed subnet, used in the stub_status allow rule

Essential commands for this stage

Hands-on

1. Create etapa07/ with backend.py, compose.yaml and nginx.conf, and run docker compose up -d. Confirm with for i in $(seq 1 6); do curl -s http://localhost:8080/; done that the responses alternate between api-1 and api-2 and never come from api-backup.
2. Run ab -n 2000 -c 50 -k http://localhost:8080/ and note Requests per second and the 95% line of the percentile table.
3. In one terminal, run for i in $(seq 1 60); do curl -s -o /dev/null -w '%{http_code} ' http://localhost:8080/; sleep 0.5; done. In another, run docker compose stop api-1. Observe that all the codes stay 200, but that the first requests that land on api-1 may take a few seconds each (the connection attempt to an IP that disappeared from the network is not refused immediately; the times vary). Confirm in docker compose logs nginx --tail 30 the lines with two upstream addresses (the first one failed) and, after the three failures of max_fails, only the address of api-2 during the 10-second window.
4. Run docker compose stop api-2 and curl -s http://localhost:8080/. Observe api-backup recebeu /: with the primaries out, the reserve takes over, and the first call may take a few seconds for the same reason as in the previous step.
5. Run docker compose start api-1 api-2, reload Nginx (docker compose exec nginx nginx -s reload) and repeat the loop from step 1. Observe the return of the primaries and the end of backup usage.
6. With api-1 up, provoke the two errors: curl -s -o /dev/null -w '%{http_code} em %{time_total}s\n' http://localhost:8080/quebrado and the same for /lento. Observe an immediate 502 and a 504 in about 2 seconds, and look for the cause with docker compose logs nginx | grep -E 'refused|timed out|unreachable|No route'.
7. Query docker compose exec tools curl -s http://nginx/nginx_status during an ab run and observe Active connections rising.
8. Clean up: docker compose down.

Stage 08 host + path

Ingress on Kubernetes

The problem

The concept

The Ingress centralizes HTTP and HTTPS routing rules under a single entry point. It is only a declaration: an API object that says "host X and path Y go to Service Z". Whoever executes these rules is the Ingress Controller (ingress-nginx, Traefik, among others), which watches the Ingress objects and configures the real proxy that receives the traffic. Without a Controller, creating the Ingress object does not change the traffic.

• Host routing separates domains (api.exemplo.com and app.exemplo.com). Path routing separates paths on the same domain (/api and /).
• pathType: Prefix accepts the path and its subpaths; Exact requires complete equality; ImplementationSpecific leaves the interpretation to the Controller (it is the type used when the path has a regular expression in ingress-nginx).
• Annotations apply features specific to the Controller, such as URL rewriting. They apply to the whole Ingress, and not to a single path. ingressClassName chooses which Controller serves the rule when there is more than one in the cluster.
• The destination Service remains a stable ClusterIP for the selected Pods. If the Service has no endpoints (ready Pods), the Ingress has nowhere to forward.

The Ingress remains stable, but its API is frozen (evolution happens in the Gateway API, gateway.networking.k8s.io, which Kubernetes recommends for new architectures). ingress-nginx, the Controller used in this lab, was retired by the Kubernetes project: the retirement was announced in November 2025 and maintenance ended in March 2026. It is still useful for studying the concept on Minikube, but for production prefer a maintained Controller or the Gateway API. This does not apply to the NGINX Ingress Controller maintained by F5, which is another project.

Path routing: the same entry address, and the URL path decides the Service. This is the case of this lab's /api.

Host routing: the request's Host header decides the Service. In both cases, the Ingress is only the rule; whoever executes it is the Ingress Controller.

Key concepts

One domain, two Services

 # apps.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api                                # "api" backend
spec:
  replicas: 2                              # two replicas
  selector:
    matchLabels:
      app: api                             # selects the Pods by label
  template:
    metadata:
      labels:
        app: api                           # must match the selector
    spec:
      containers:
        - name: api
          image: python:3.12-alpine        # image with Python
          command: ["python", "/app/backend.py"]   # runs the didactic backend
          env:
            - name: NAME
              value: api                   # name returned in the responses
          ports:
            - containerPort: 3000          # backend port
          readinessProbe:                  # only receives traffic when it answers
            httpGet:
              path: /healthz
              port: 3000
          volumeMounts:
            - name: code
              mountPath: /app              # the script appears at /app/backend.py
      volumes:
        - name: code
          configMap:
            name: backend-py               # ConfigMap created from backend.py
---
apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api                               # forwards to the Pods with this label
  ports:
    - port: 80                             # Service port
      targetPort: 3000                     # container port
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web                                # same template, another name
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: python:3.12-alpine
          command: ["python", "/app/backend.py"]
          env:
            - name: NAME
              value: web                   # the only field that changes
          ports:
            - containerPort: 3000
          readinessProbe:
            httpGet:
              path: /healthz
              port: 3000
          volumeMounts:
            - name: code
              mountPath: /app
      volumes:
        - name: code
          configMap:
            name: backend-py
---
apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 3000

Essential commands for this stage

Hands-on

1. Start the cluster and the Controller: minikube start -p lab, minikube addons enable ingress -p lab and the kubectl wait above. Observe the ingress-nginx-controller Pod in Running and confirm the nginx class with kubectl get ingressclass.
2. Create the ConfigMap (kubectl create configmap backend-py --from-file=backend.py) and apply apps.yaml and ingress.yaml. Confirm the Pods with kubectl get pods and the endpoints with kubectl get endpointslices.
3. Open the port-forward in another terminal (kubectl port-forward -n ingress-nginx svc/ingress-nginx-controller 8080:80, which stays in the foreground) and, in the original terminal, run curl -s -H 'Host: pitstop.local' http://127.0.0.1:8080/api/health and the same for /. Observe api recebeu /health (the /api prefix was removed by the rewrite) and web recebeu /.
4. Test /status and /status/extra with the same Host header. Observe that Exact matches only the exact path and that the subpath falls into the frontend's / rule.
5. Run kubectl exec ... cat /etc/nginx/nginx.conf | grep -n pitstop.local and observe that the Controller turned the Ingress objects into server blocks of a real Nginx.
6. Provoke a failure: kubectl scale deployment api --replicas=0 and repeat /api/health. Observe the Controller's 503 response (Service without endpoints) and restore with --replicas=2.
7. End the port-forward (Ctrl+C in the other terminal) and delete only the rules: kubectl delete -f ingress.yaml. Keep the lab profile, the applied apps.yaml and the backend-py ConfigMap, because Stage 09 uses the web Service. The full cleanup comes at the end of Stage 09.

Stage 09 cert-manager

TLS and cert-manager

The problem

The concept

TLS offers confidentiality, integrity and server authentication. cert-manager extends the Kubernetes API with declarative resources to issue, store and renew certificates automatically.

• Issuer issues certificates within a namespace; ClusterIssuer serves the whole cluster. They define the issuing authority (self-signed, an internal CA or ACME).
• Certificate declares the DNS names, the duration and the Secret that will receive the private key and the certificate.
• With ACME (the protocol used by Let's Encrypt), an HTTP-01 challenge (publishing a token at a path of the site) or DNS-01 (publishing a TXT record) proves control of the domain. cert-manager tracks the validity and renews before expiry (by default, the duration is 90 days and renewal starts when a third of it remains).
• The Ingress references the TLS Secret. With the cert-manager.io/cluster-issuer annotation, cert-manager creates the Certificate on its own from the Ingress's tls block.
• On the connection, the client states the name of the site it wants right at the start of the handshake (SNI), and that is why a single Controller can present the right certificate for each host.

The private key stays in the cluster and must not be written to manifests or repositories. A Secret is base64-encoded, and that is not encryption: the protection comes from access control (RBAC) over the Secrets.

The ACME challenge requires a public domain reachable by the authority, so Let's Encrypt can only be practiced with a real domain. The lab uses a self-signed ClusterIssuer, which exercises the same path (Ingress, Certificate, Secret, renewal) without depending on the public internet. When using Let's Encrypt for real, start with the staging environment to avoid the issuance limits.

Key concepts

Ingress integrated with cert-manager

 # clusterissuer-selfsigned.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned                         # name cited in the annotations
spec:
  selfSigned: {}                           # issues self-signed certificates (lab only)

Essential commands for this stage

Hands-on

1. In the lab cluster, confirm that apps.yaml and the backend-py ConfigMap from Stage 08 are still applied (kubectl get svc web). If you deleted them, recreate them with kubectl create configmap backend-py --from-file=backend.py and kubectl apply -f apps.yaml, using the files from the etapa08/ folder. Install cert-manager with the three helm commands from the example and confirm the three Running Pods with kubectl get pods -n cert-manager.
2. Apply clusterissuer-selfsigned.yaml and ingress-tls.yaml. Run kubectl get certificate -w and observe READY go from False to True. Confirm the Secret with kubectl get secret pitstop-tls and observe the kubernetes.io/tls type.
3. In another terminal, open the port-forward for port 443 (kubectl port-forward -n ingress-nginx svc/ingress-nginx-controller 8443:443). In the original terminal, first run curl -sk --resolve secure.pitstop.local:8443:127.0.0.1 https://secure.pitstop.local:8443/ and observe the web recebeu / response. Then run the same command with -v and 2>&1 | grep -iE 'subject:|issuer:' and observe that the delivered certificate is no longer the Controller's Kubernetes Ingress Controller Fake Certificate (the cert-manager certificate does not define a common name, so subject and issuer may come empty; the site's name appears in the subjectAltName extension, which step 4 shows).
4. Inspect the Secret's certificate with the openssl from the example and observe the issuer= line, the DNS name in subjectAltName and the validity.
5. Apply certificate-renova.yaml, wait about 6 minutes and run kubectl describe certificate renova-teste. Observe a renewal event and Revision: 2 in the status.
6. Show that base64 is not encryption: kubectl get secret pitstop-tls -o jsonpath='{.data.tls\.key}' | base64 -d | head -n 1 shows the start of the private key in plain text. Explain which access controls (RBAC) protect the Secret.
7. Clean up everything from Stage 08 and this one: end the port-forward (Ctrl+C), run kubectl delete -f ingress-tls.yaml -f certificate-renova.yaml, kubectl delete secret pitstop-tls renova-teste-tls, kubectl delete -f ../etapa08/apps.yaml, kubectl delete configmap backend-py and, finally, minikube delete -p lab. Two clusters running at the same time are heavy, and Stage 10 brings up a new profile (mesh) with 4 CPUs and 8 GB.

Stage 10 istio + sidecars

Service Mesh and Istio's architecture

The problem

The concept

In Istio's sidecar model, an Envoy proxy is injected into each Pod, next to the application container, and intercepts inbound and outbound traffic. The application stays focused on the business rule.

• The Data Plane is made up of the Envoy proxies: they process the requests and apply routing, resilience, security and telemetry.
• The Control Plane is Istiod: it watches services and Istio resources, translates the high-level rules into Envoy configuration, distributes service discovery and issues the workloads' identities (certificates).
• Injection is enabled per namespace (istio-injection=enabled) and happens when the Pod is created: Pods that already exist only get the sidecar when they are recreated (for example, with kubectl rollout restart).

The abstraction has a cost: each sidecar consumes CPU and memory, adds latency per hop and the mesh is an additional platform to update and diagnose. For a few services, the benefit may not pay off. Istio also offers ambient mode, without sidecars; this guide uses sidecars because the path of the traffic stays visible.

Key concepts

Installation, injection and sidecar validation

 # app.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: web                                # client identity (used in Stage 12)
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-v1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
      version: v1
  template:
    metadata:
      labels:
        app: api                           # label recommended by Istio
        version: v1                        # version: basis of the Stage 11 subsets
    spec:
      containers:
        - name: api
          image: python:3.12-alpine
          command: ["python", "/app/backend.py"]
          env:
            - name: NAME
              value: api-v1                # name returned in the responses
          ports:
            - containerPort: 3000
          volumeMounts:
            - name: code
              mountPath: /app
      volumes:
        - name: code
          configMap:
            name: backend-py
---
apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api                               # selects all versions of the api
  ports:
    - name: http                           # the name http tells the mesh the protocol
      port: 80
      targetPort: 3000
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      serviceAccountName: web              # the client calls the api with the "web" identity
      containers:
        - name: web
          image: curlimages/curl
          command: ["sleep", "86400"]      # stays idle; we will use kubectl exec to call the api

Essential commands for this stage

Hands-on

1. Go into etapa10/ and run the first three commands of the example (download, cd istio-* && export PATH=$PWD/bin:$PATH && cd - and minikube start). Confirm with pwd that you are back in etapa10/, install Istio with istioctl install --set profile=demo -y and observe Installation complete. Run kubectl get pods -n istio-system to see istiod and the gateways in Running.
2. Still in etapa10/, create the demo namespace, the ConfigMap and apply app.yaml. Observe READY 1/1 on both Pods, without a sidecar.
3. Enable injection, run kubectl rollout restart deployment -n demo and observe READY 2/2. Run kubectl get pod -n demo -l app=api -o jsonpath='{.items[0].spec.containers[*].name}' and observe the api and istio-proxy containers.
4. Run istioctl proxy-status and observe the proxies of api-v1 and web in SYNCED. Also run the reserved resources command and record the proxy's cost in CPU and memory.
5. Test the internal call: kubectl exec -n demo deploy/web -c web -- curl -s http://api/. Observe api-v1 recebeu /, now passing through two proxies.
6. Create the legacy namespace without the label (kubectl create namespace legacy), copy the ConfigMap (kubectl create configmap backend-py --from-file=backend.py -n legacy) and apply app.yaml with -n legacy. Observe READY 1/1 and explain where the mesh's policies stop acting: on Pods without a sidecar, no Istio policy is applied.
7. Keep the mesh cluster and the demo namespace for Stages 11 and 12. Clean up legacy with kubectl delete namespace legacy.

Stage 11 canary + mirror

VirtualService, DestinationRule and gradual deployment

The problem

The concept

In Istio, two rules work together. The DestinationRule names groups of Pods (subsets, selected by labels such as version: v1) and defines connection policies for the destination. The VirtualService decides how each call travels through those groups: weights, conditions by header or path, retries, timeouts, mirroring and simulated failures. The rules are applied by the client's sidecar, so they only apply to calls that go through a mesh proxy.

Three ways of testing a version:

• Canary by weight sends a small percentage of real traffic to the new version and widens it gradually. The weights of a route must add up to 100.
• A/B testing uses characteristics of the request (header, cookie, path) to segment users, for example always sending a test user to v2.
• Traffic mirroring duplicates the calls to the new version and discards its response: the client keeps receiving v1, and v2 receives real load with no risk to the user.

Resilience in the same resource: retries help with transient failures, but multiply the load if they are not limited. attempts is the number of new attempts after the first, perTryTimeout limits each attempt and the route's timeout limits the total time, which must accommodate all the attempts. Circuit breaking (in the DestinationRule, with outlierDetection) ejects endpoints that fail repeatedly, to avoid cascades. Fault injection (fault, with delay or abort) lets you test how applications react.

Weight is the delivery mechanism, not the success criterion: the decision to widen the canary comes from error rate, latency and business metrics.

Key concepts

Ninety percent v1, ten percent v2

 # api-v2.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-v2
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
      version: v2
  template:
    metadata:
      labels:
        app: api                           # the "api" Service selects this Pod too
        version: v2                        # distinguishes v2 from v1
    spec:
      containers:
        - name: api
          image: python:3.12-alpine
          command: ["python", "/app/backend.py"]
          env:
            - name: NAME
              value: api-v2
          ports:
            - containerPort: 3000
          volumeMounts:
            - name: code
              mountPath: /app
      volumes:
        - name: code
          configMap:
            name: backend-py

Essential commands for this stage

Hands-on

1. Apply api-v2.yaml and confirm READY 2/2 on both api Pods. Run kubectl get endpointslices -n demo -l kubernetes.io/service-name=api and observe two endpoints: the Service selects both versions.
2. With no VirtualService, count 100 responses with the loop from the example. Observe a split close to 50 and 50, the behavior of the plain Service.
3. Apply canary.yaml, run istioctl analyze -n demo and count 100 responses again. Observe about 90 for v1 and 10 for v2 (the split is statistical, so the numbers vary).
4. Send curl -s -H 'x-usuario: teste' http://api/ through the web client several times. Observe api-v2 in all the responses, and the same command without the header going back to the 90/10 split.
5. Apply mirror.yaml, send 10 calls through the client and observe that all the responses are api-v1. Then run kubectl logs -n demo deploy/api-v2 -c api --tail 12 and observe the 10 requests reaching v2, even though the client does not receive its response.
6. Practice the rollback: kubectl delete virtualservice api -n demo and count 100 responses. Observe the return to the Service's split. If something looks wrong, run istioctl analyze before attributing the deviation to the proxy.
7. Keep the cluster for Stage 12 and leave it without a VirtualService, as after the rollback in step 6. If you reapply canary.yaml or mirror.yaml, the Stage 12 responses will also come from v2 and the counters read only on api-v1 will differ from the ones shown there.

Stage 12 identity + metrics

mTLS, authorization and observability in the mesh

The problem

The concept

Istio authenticates workloads with short-lived certificates issued by Istiod, encrypts traffic between sidecars with mTLS (both ends present an identity) and authorizes calls by identity, which is derived from the Pod's ServiceAccount (cluster.local/ns/demo/sa/web).

• PeerAuthentication controls mTLS. PERMISSIVE accepts traffic with and without mTLS and helps with migrations; STRICT rejects traffic without a mesh identity. The policy named default in a namespace applies to the whole namespace.
• AuthorizationPolicy answers what an authenticated identity can do, by source, method and path. When an ALLOW policy exists for a workload, every request that does not match any rule is denied (HTTP 403).
• Observability: Envoy records volume, response code and duration of each call. Prometheus stores metrics, Grafana presents dashboards, Jaeger reconstructs traces and Kiali shows the topology, the errors and the mTLS state.
• Distributed tracing: the proxy creates and reads tracing headers, but the application needs to propagate them in the following calls (x-request-id, x-b3-traceid, x-b3-spanid, x-b3-parentspanid, x-b3-sampled, x-b3-flags, b3 and, for W3C, traceparent and tracestate). Without propagation, the trace breaks even with healthy sidecars. Collecting traces requires configuring a tracing provider in the mesh, which is outside the lab; here you check the headers and the metrics.

Authentication answers who it is; authorization answers what it can do. mTLS does not replace an access policy.

Key concepts

Strict mTLS, identity-based policy and metrics

 # mtls-strict.yaml
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default                            # policy for the whole namespace
  namespace: demo
spec:
  mtls:
    mode: STRICT                           # rejects traffic without mTLS

Essential commands for this stage

Hands-on

1. With the mesh cluster, create the legacy namespace and a test Pod without a sidecar (commands from the example). Call the api and observe that, in PERMISSIVE, the call without mTLS works.
2. Apply only the PeerAuthentication: kubectl apply -f mtls-strict.yaml. Repeat the call from legacy and observe the refusal. Repeat the call through web (which has a sidecar) and observe that it keeps working.
3. Apply outro.yaml (it already declares namespace: demo) and confirm that the outro Pod has READY 2/2. Before applying the policy, run kubectl exec -n demo deploy/outro -c outro -- curl -s -o /dev/null -w '%{http_code}\n' http://api/api/ping and observe 200, because there is no authorization rule yet. Apply authz-api.yaml, run the four calls from item 4 of the example and observe 200 only for GET /api/ping coming from web, and 403 for another path, another method and another identity (outro).
4. Run the call to /api/headers and observe that the proxy added X-Request-Id and X-Forwarded-Client-Cert with the caller's identity. Explain why, for a complete trace, the application needs to copy these headers into the calls it makes itself.
5. Run istioctl proxy-config secret deploy/api-v1 -n demo and read Envoy's metrics on the sidecar. Observe istio_requests_total counters separated by response code, including the 403s you provoked. Since api-v2 also serves the Service, repeat the reading on deploy/api-v2 and add up the counters if the calls went to both.
6. Optional: install Prometheus and Kiali (samples/addons inside the istio-* folder in etapa10/), generate traffic with a curl loop and open istioctl dashboard kiali. Observe the web to api graph and the mTLS padlock icon.
7. Clean up everything at the end of Stages 10 to 12: minikube delete -p mesh.

Stage 13 slo + spof + vrrp

High availability: SLA, SLO, SPOF and redundancy

The problem

The concept

• SLA is the external promise to the client, possibly with a penalty. SLO is the internal target used by engineering, usually stricter than the SLA. The error budget is what the SLO allows in failure over the period (100% minus the SLO). A target of 99.9% over 30 days allows about 43 minutes of unavailability.
• A SPOF (single point of failure) is any server, balancer, link, database or location whose failure interrupts the whole service. Components in series multiply availabilities (two 99.9% components give about 99.8%), while independent replicas in parallel improve them (two 99% ones give about 99.99%, if the failures are independent). SPOFs must be removed, reduced or explicitly accepted.
• Active-passive keeps a reserve instance and requires failover; it simplifies consistency. Active-active uses all the nodes at the same time and redistributes the load when one fails, but requires stateless applications or correct state synchronization.
• Keepalived with VRRP moves a virtual IP (VIP) between two balancers: the node with the highest priority and confirmed health answers for the VIP, and if it fails the other takes over. The configuration of both nodes must be kept in sync by automation (such as Ansible) or by declarative mechanisms. In many cloud networks VRRP does not work as on a local network, and the provider offers managed balancers or IP reassignment; check your provider's documentation.
• Health checks must verify the real function (for example, a valid HTTP response), not just the existence of the process.
• Chaos Engineering formulates a hypothesis, injects a controlled failure and measures the reaction, with clear criteria for aborting. It is not random failure in production.
• HA reduces local interruptions; Disaster Recovery (DR) recovers the service after broad events, such as the loss of a zone or region. The RTO is the maximum time accepted to recover and the RPO is the maximum data loss accepted, measured in time.

Before the failure: lb1 has the highest priority and a passing check_nginx, so it answers for the virtual IP.

After nginx -s stop on lb1: two consecutive check_nginx failures take lb1 out of the role, lb2 takes the VIP, and the client keeps using the same address.

Key concepts

Keepalived protecting the balancer

# Dockerfile
FROM nginx:stable
# keepalived does the VRRP; curl and iproute2 serve the health check and the IP inspection
RUN apt-get update \
 && apt-get install -y --no-install-recommends keepalived curl iproute2 \
 && rm -rf /var/lib/apt/lists/*

Essential commands for this stage

Hands-on

1. Draw on paper the complete path of a request (client, DNS, balancer, application, database) and mark each component without redundancy. Each mark is a SPOF.
2. Choose an availability SLO for the service and calculate the allowed monthly downtime with the awk command from the example. Also calculate the availability of two 99.9% components in series.
3. Create etapa13/ with the example's files and run docker compose up -d --build. Find out which node has the VIP and observe atendido por lb1 when calling the virtual IP.
4. In one terminal, run the client loop. In another, stop lb1's Nginx with docker compose exec lb1 nginx -s stop. Observe responses from lb1, one or two failures and then responses from lb2, and measure how many seconds passed without a response.
5. Run docker compose exec lb1 nginx and observe the VIP return to lb1 (higher priority) after the health checks pass. Also record the state transitions in docker compose logs.
6. Write a Chaos Engineering hypothesis (for example, "if the active balancer goes down, the client loses at most 5 seconds of response") with an abort criterion (for example, "if the VIP does not migrate in 30 seconds, restore the node and end the experiment"). Compare the result of step 4 with the hypothesis.
7. Clean up: docker compose down.

Stage 14 modsecurity + rate limit

WAF, rate limiting and defense in depth

The problem

The concept

Layer 3 and 4 firewalls block networks and ports, but do not inspect the application layer. A WAF (Web Application Firewall) inspects the HTTP content. ModSecurity (with the libModSecurity library and the connector for Nginx) is the engine that applies the rules, and the OWASP Core Rule Set (CRS) is a community-maintained rule base against patterns such as SQL Injection and XSS.

• The WAF evaluates the rules and accumulates an anomaly score; when it goes over a threshold, it blocks (by default in the CRS, the inbound threshold is 5). It can only log (DetectionOnly) or block (On). Start in detection mode to adjust false positives before interrupting legitimate users. The CRS also has paranoia levels (from 1 to 4): higher levels detect more and generate more false positives.
• TLS 1.2 or 1.3, HSTS and secure headers protect the channel and the browser. HSTS tells the browser to use only HTTPS for the domain for the time given in max-age.
• Rate limiting limits requests per key (usually the IP) and helps against brute force and abuse, but does not replace protection against distributed DDoS, in which each source sends little. In Nginx, limit_req_zone defines the key, the memory and the rate; limit_req applies the limit in a location; burst allows bursts and nodelay serves the burst without delay. The default rejection response is 503; use limit_req_status 429 to return 429 Too Many Requests. Behind a NAT, several users share the same IP, and behind a CDN or proxy you need to configure the client's real IP.
• Nginx and ModSecurity logs need to reach a central platform, with alerts for increases in blocks, 5xx responses and latency. Security depends on review, CRS updates and repeatable tests.

A WAF does not fix the vulnerability in the code: it reduces exposure and buys time for the definitive fix. Defense works in layers, each covering what the previous one does not see.

Key concepts

A layered edge, with TLS, rate limit and WAF

 # compose.yaml
services:
  api:
    image: python:3.12-alpine
    command: ["python", "/app/backend.py"]
    environment:
      NAME: api
    volumes:
      - ./backend.py:/app/backend.py:ro
  crs:
    image: owasp/modsecurity-crs:nginx              # WAF: Nginx with ModSecurity and OWASP CRS
    environment:
      BACKEND: http://api:3000                      # where the WAF forwards the approved traffic
      PORT: "8080"                                  # WAF listening port inside the container
      MODSEC_RULE_ENGINE: DetectionOnly             # only logs; change to On to block
      PARANOIA: "1"                                 # CRS paranoia level (1 is the least sensitive)
    depends_on: [api]
  edge:
    image: nginx:stable                             # edge: TLS, HSTS and rate limit
    ports:
      - "8443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on: [crs]

Essential commands for this stage

Hands-on

1. Create etapa14/ with backend.py, compose.yaml, nginx.conf and the certs/ folder, and run docker compose up -d. If edge returns 502, check with docker compose logs crs which port the WAF listens on and adjust PORT and the proxy_pass. If you edit nginx.conf later, run docker compose exec edge nginx -s reload and, if the change does not show up, docker compose restart edge.
2. Send a normal request (curl -sk https://localhost:8443/) and observe api recebeu /, passing through edge, WAF and backend.
3. With the WAF in DetectionOnly, send the XSS payload and the SQL Injection one from the example. Observe the 200 and look in docker compose logs crs for the rule triggered (a rule id and the message). Identify the rule before enabling blocking.
4. Switch MODSEC_RULE_ENGINE to On, run docker compose up -d and repeat the payloads. Observe 403. Send a normal request again and observe that it is still 200.
5. Run the 10 consecutive calls to /login and observe the 429s after the limit. Wait about 12 seconds and repeat one call to observe the limit releasing a slot.
6. Check the headers with curl -sk -I https://localhost:8443/ and observe strict-transport-security, and the absence of the version in the server header.
7. Build a checklist for your service: TLS 1.2 or 1.3, HSTS, CRS updates, log retention, alerts for spikes in blocks and 5xx, and a repeatable test of the payloads.
8. Clean up: docker compose down.

Stage 15 · review

Self-assessment checklist

Next steps: with all items checked, redo the labs without consulting the guide and then put the pieces together. On Docker, build an edge with two backends behind an Nginx with balancing, a backup server, rate limiting and a WAF, and protect that Nginx with a second node and Keepalived. On Minikube, publish the same application with Ingress and cert-manager TLS and do a 90/10 canary with Istio, measuring the real proportion and practicing the rollback.