a. Visão geral

No lab 2 você encontrou o joelho de uma única instância do catalog. O jeito mais simples de deslocá-lo é a escala horizontal: mais cópias idênticas e stateless do serviço atrás de um balanceador de carga. A mesma caixa resolve um segundo problema — com uma instância, uma queda ou um deploy derruba o BoxOffice. Com três, uma pode falhar enquanto as outras continuam atendendo. Este lab constrói a borda do sistema: a única porta de entrada pública que toda requisição atravessa primeiro.

Antes de começar

docker compose version        # Docker Compose v2.x (or newer)
java -version                 # 21 or newer
mvn -v                        # Apache Maven 3.9+
k6 version                    # k6 v1.0+
uv --version                  # uv (runs the Python helper scripts)

Estado inicial — o fim do lab 2:

📁 boxoffice/
├──  docker-compose.yaml        # db + catalog
├── 📁 load/  hello.js smoke.js load.js stress.js
├── 📁 results/  lab0.md lab1.md lab2.md lab2/ ...
├── 📁 scripts/  check-env.sh sweep.sh summarize.py watch-metrics.sh
└── 📁 services/catalog/

Slides

Clique nos slides e use ← → para navegar; F abre em tela cheia e P abre a visão do apresentador, com as notas. Abrir os slides em uma nova aba

Antes de medir: o playground

Experimente: o cenário scale-out tem um balanceador de carga na frente de réplicas da aplicação. Rode-o com as réplicas padrão, depois mude o número de servidores de aplicação (1 → 2 → 4) e compare throughput e p99. Por fim, mate uma réplica enquanto a carga roda: quanto tempo até o balanceador parar de mandar tráfego para ela? Anote as suas previsões para o sistema real — 3× as réplicas dá 3× o throughput?

O que você vai construir

flowchart LR
    k6([k6 / fãs]) -->|":80"| edge["edge<br/>Nginx 1.30"]
    edge -->|round robin| c1["catalog-1<br/>1 CPU"]
    edge --> c2["catalog-2<br/>1 CPU"]
    edge --> c3["catalog-3<br/>1 CPU"]
    c1 --> db[("db<br/>PostgreSQL")]
    c2 --> db
    c3 --> db

Só a borda publica uma porta (80). As réplicas só são alcançáveis dentro da rede do Compose — o mesmo formato de um balanceador de carga público na frente de instâncias privadas numa VPC na nuvem (aula 12).

1. Torne as réplicas visíveis

Quando três réplicas respondem, você quer saber qual respondeu. Acrescente este filtro ao catalog; ele carimba toda resposta com o hostname do container:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

package boxoffice.catalog;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

/** Adds "X-Instance: catalog-2" to every response: which replica answered? */
@Component
public class InstanceHeaderFilter extends OncePerRequestFilter {

    // Docker sets HOSTNAME to the container's hostname (catalog-1, catalog-2, ...)
    private final String instance = System.getenv().getOrDefault("HOSTNAME", "local");

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        response.setHeader("X-Instance", instance);
        chain.doFilter(request, response);
    }
}

Essa é a única mudança de código deste lab. Todo o resto é configuração — um bom sinal: um serviço stateless escala horizontalmente sem mexer no código.

2. Três réplicas no Compose

Substitua o seu docker-compose.yaml. O bloco x-catalog é uma âncora YAML: uma definição, reaproveitada por catalog-1, catalog-2 e catalog-3; cada um só acrescenta o próprio hostname.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

name: boxoffice

# settings shared by the three catalog replicas (a YAML anchor)
x-catalog: &catalog
  build: ./services/catalog
  image: boxoffice-catalog
  environment:
    DB_HOST: db
    DB_PORT: 5432
    DB_NAME: ${DB_NAME:-boxoffice}
    DB_USER: ${DB_USER:-boxoffice}
    DB_PASSWORD: ${DB_PASSWORD:-boxoffice}
    DB_POOL_SIZE: ${DB_POOL_SIZE:-10}
  depends_on:
    db:
      condition: service_healthy
  deploy:
    resources:
      limits:
        cpus: "1.0"
        memory: 768M
  healthcheck:
    test: ["CMD-SHELL", "wget -qO- http://localhost:8082/actuator/health/readiness || exit 1"]
    interval: 10s
    timeout: 3s
    start_period: 40s
    retries: 3

services:

  db:
    image: postgres:17
    environment:
      POSTGRES_DB: ${DB_NAME:-boxoffice}
      POSTGRES_USER: ${DB_USER:-boxoffice}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-boxoffice}
    ports:
      - "5432:5432"
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 3s
      retries: 10

  # three identical replicas; no "ports:" — only the edge is reachable from outside
  catalog-1:
    <<: *catalog
    hostname: catalog-1
  catalog-2:
    <<: *catalog
    hostname: catalog-2
  catalog-3:
    <<: *catalog
    hostname: catalog-3

  edge:
    image: nginx:1.30-alpine
    ports:
      - "80:80"
    volumes:
      - ./infra/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - catalog-1
      - catalog-2
      - catalog-3

volumes:
  db-data:

3. A borda: nginx.conf

O Nginx¹ lê um arquivo de configuração. Toda diretiva abaixo aparece nele, na mesma ordem.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# BoxOffice edge: reverse proxy + load balancer + rate limiter (lab 3)
user  nginx;
worker_processes  auto;

events {
    worker_connections  4096;
}

http {
    # one line per request: who served it, and how long the upstream took
    log_format  edge  '$remote_addr "$request" $status rt=$request_time '
                      'upstream=$upstream_addr ut=$upstream_response_time id=$request_id';
    access_log  /var/log/nginx/access.log  edge;

    # Docker's embedded DNS: lets nginx start even if a replica is down, and
    # notice replicas that come back (the "resolve" flag below, nginx >= 1.27.3)
    resolver  127.0.0.11  valid=10s  ipv6=off;

    upstream catalog {
        zone catalog 64k;                 # shared memory, required by "resolve"
        # least_conn;                     # try it: pick the replica with fewest active requests
        server catalog-1:8082 resolve max_fails=3 fail_timeout=10s;
        server catalog-2:8082 resolve max_fails=3 fail_timeout=10s;
        server catalog-3:8082 resolve max_fails=3 fail_timeout=10s;
        keepalive 64;                     # reuse TCP connections to the replicas
    }

    # rate limiting per API key: 20 req/s per key, bursts of up to 40.
    # Requests WITHOUT an X-Api-Key header have an empty key and are not limited
    # (in production you would also limit them per client IP).
    limit_req_zone  $http_x_api_key  zone=per_key:10m  rate=20r/s;
    limit_req_status  429;

    server {
        listen  80;

        # the edge's own liveness: does not touch any backend
        location = /healthz {
            access_log  off;
            return  200  "ok\n";
        }

        location /catalog/ {
            limit_req  zone=per_key  burst=40  nodelay;

            proxy_pass  http://catalog;
            proxy_http_version  1.1;
            proxy_set_header  Connection         "";      # keep upstream connections alive
            proxy_set_header  Host               $host;
            proxy_set_header  X-Real-IP          $remote_addr;
            proxy_set_header  X-Forwarded-For    $proxy_add_x_forwarded_for;
            proxy_set_header  X-Forwarded-Proto  $scheme;
            proxy_set_header  X-Request-Id       $request_id;
            add_header        X-Request-Id       $request_id always;

            # passive health checking: a failed attempt is retried on another replica
            proxy_connect_timeout  1s;
            proxy_read_timeout     5s;
            proxy_next_upstream    error timeout http_502 http_503 http_504;
            proxy_next_upstream_tries  2;
        }

        # nothing else is public (no /actuator from the internet)
        location / {
            return  404;
        }
    }
}

4. Rode e observe a distribuição

docker compose up --build -d --remove-orphans   # removes the old single 'catalog' container of lab 1
docker compose ps                       # catalog-1..3 healthy, edge running
curl -s localhost/healthz               # the edge itself
for i in $(seq 1 9); do curl -s -o /dev/null -D - localhost/catalog/events/1 | grep -i x-instance; done | sort | uniq -c

Round robin: cada réplica recebe uma de cada três requisições. Compare rt (o tempo total na borda) com ut (o tempo gasto na réplica): a diferença é o custo do salto extra.

5. Falhas: parar, congelar, recuperar

Rode uma carga constante num terminal e quebre coisas em outro:

# terminal 1: 2 minutes at 150 req/s through the edge
BASE_URL=http://localhost k6 run -e RATE=150 -e DURATION=2m load/load.js

# terminal 2, while it runs:
docker compose stop catalog-2          # a crash: connections are refused immediately
sleep 20
docker compose start catalog-2         # it comes back (startup takes ~10 s)
sleep 30
docker compose pause catalog-3         # a freeze (GC pause, stuck disk): connections hang
sleep 20
docker compose unpause catalog-3

O que procurar no resumo do k6 e em docker compose logs edge:

Você deve ver algo assim no fim da execução do k6 (uma execução deste lab: nenhum erro, mas a pausa aparece na cauda; o p99 pode ficar entre ~1 s e ~5 s, conforme quantas requisições o congelamento pegou):

    http_req_duration..............: avg=48.31ms med=1.33ms p(95)=25.56ms p(99)=1s       max=5.05s
    http_req_failed................: 0.00%  0 out of 14990

A lição: uma réplica morta é fácil; uma lenta é perigosa. Os timeouts decidem quanto uma réplica lenta custa. O Nginx open source só tem checks passivos² (ele aprende com requisições reais que falharam); checks ativos — sondar /actuator/health/readiness a cada poucos segundos — existem no Nginx Plus, no HAProxy, no Envoy, nos balanceadores de carga da nuvem e nas readiness probes do Kubernetes (lab 10).

6. Rate limiting

Uma integração de parceiro que consulta o catalog 50 vezes por segundo pode deixar todo mundo sem atendimento. A borda dá a cada chave de API 20 req/s com uma rajada de 40; acima disso, responde 429 Too Many Requests sem incomodar as réplicas.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// Lab 3: two API clients share the edge. "greedy" sends 50 req/s, "polite" 10 req/s;
// the edge allows 20 req/s per X-Api-Key (burst 40). Who gets 429?
//   k6 run load/ratelimit.js
import http from 'k6/http';
import { check } from 'k6';

const BASE_URL = __ENV.BASE_URL || 'http://localhost';

export const options = {
  scenarios: {
    greedy: {
      executor: 'constant-arrival-rate', rate: 50, timeUnit: '1s', duration: '30s',
      preAllocatedVUs: 20, env: { API_KEY: 'partner-greedy' },
    },
    polite: {
      executor: 'constant-arrival-rate', rate: 10, timeUnit: '1s', duration: '30s',
      preAllocatedVUs: 10, env: { API_KEY: 'partner-polite' },
    },
  },
  thresholds: {
    // listed only so that k6 prints one line per scenario and status
    'http_reqs{scenario:greedy,status:200}': ['count>=0'],
    'http_reqs{scenario:greedy,status:429}': ['count>=0'],
    'http_reqs{scenario:polite,status:200}': ['count>=0'],
    'http_reqs{scenario:polite,status:429}': ['count>=0'],
  },
};

export default function () {
  const res = http.get(`${BASE_URL}/catalog/events/1`, { headers: { 'X-Api-Key': __ENV.API_KEY } });
  check(res, { 'answered 200 or 429': (r) => r.status === 200 || r.status === 429 });
}

k6 run load/ratelimit.js

Você deve ver (de uma execução deste lab — 30 s a 50 e a 10 req/s):

    http_reqs{scenario:greedy,status:200}
    ✓ 'count>=0' count=640
    http_reqs{scenario:greedy,status:429}
    ✓ 'count>=0' count=843
    http_reqs{scenario:polite,status:200}
    ✓ 'count>=0' count=299
    http_reqs{scenario:polite,status:429}
    ✓ 'count>=0' count=0

Formato esperado (as contagens variam): o cliente polite (10 req/s) só recebe 200; o greedy (50 req/s) recebe cerca de 20 200 por segundo e o resto 429. O Nginx implementa um leaky bucket: as requisições escoam a rate; burst é o tamanho do balde; nodelay atende a rajada imediatamente em vez de espaçá-la.

7. Meça: 3× as réplicas dá 3× o throughput?

Use a varredura do lab 2, agora pela borda, com duas cargas diferentes — a resposta depende de qual recurso é o gargalo:

• Só detalhes (LIST_SHARE=0): buscas por chave primária, baratas para o PostgreSQL. O limite é a CPU de cada réplica (1 núcleo).
• A mistura do lab 2 (LIST_SHARE=0.2): 20% de listagens, cada uma varrendo e ordenando milhares de linhas. O limite é o PostgreSQL, que todas as réplicas compartilham.

Primeiro com uma réplica (pare as outras duas; o Nginx as remove), depois com três:

# 1 replica behind the edge
docker compose stop catalog-2 catalog-3 && sleep 15   # Nginx re-resolves the names every 10 s (resolver valid=10s)
LIST_SHARE=0 BASE_URL=http://localhost OUT=results/lab3-1replica-detail bash scripts/sweep.sh 300 600 900 1200 1500
BASE_URL=http://localhost OUT=results/lab3-1replica-mix bash scripts/sweep.sh 100 200 300 400 500

# 3 replicas behind the edge: start them and WARM THEM UP before measuring
docker compose start catalog-2 catalog-3 && sleep 30
BASE_URL=http://localhost k6 run -e RATE=300 -e DURATION=2m load/load.js > /dev/null
LIST_SHARE=0 BASE_URL=http://localhost OUT=results/lab3-3replicas-detail bash scripts/sweep.sh 600 1200 1800 2400 3000
BASE_URL=http://localhost OUT=results/lab3-3replicas-mix bash scripts/sweep.sh 100 200 300 400 500

for d in results/lab3-*; do echo "## $d"; uv run scripts/summarize.py $d/rate-*.json; done

Deixe o docker stats aberto durante cada execução e anote qual container está no limite: catalog-* perto de 100% (um núcleo cada) ou o db usando vários núcleos.

Registre em results/lab3.md:

# Lab 3 — scale-out behind the edge

## Sweeps
<the four tables from summarize.py: 1/3 replicas × detail/mix>

## Capacity (highest rate with p99 < 300 ms and no errors)
| Workload | Replicas | Capacity (req/s) | Container at its limit (docker stats) |
|---|---:|---:|---|
| details only | 1 | | |
| details only | 3 | | |
| lab 2 mix | 1 | | |
| lab 2 mix | 3 | | |

Scaling efficiency = capacity(3) / (3 × capacity(1)):
- details only: ____ %
- lab 2 mix: ____ %
- Why are they so different? ____

## Edge overhead
- p50 direct to catalog (lab 2, same rate): ____ ms; p50 through the edge: ____ ms

## Failures (step 5)
- stop catalog-2: errors ____, p99 ____ ms
- pause catalog-3: errors ____, p99 ____ ms; how long until Nginx stopped sending it traffic? ____ s

## Rate limiting (step 6)
| Client | Sent | 200 | 429 |
|---|---:|---:|---:|
| greedy (50 req/s) | | | |
| polite (10 req/s) | | | |

Solução de problemas

Limpeza

docker compose start catalog-2 catalog-3     # if you left them stopped after the sweep
docker compose unpause catalog-3 2>/dev/null || true
docker compose down                          # when you are done (the database volume is kept)

Guarde tudo: o lab 4 coloca o gateway atrás desta borda.

Entrega

• O InstanceHeaderFilter, o docker-compose.yaml com três réplicas e o infra/nginx/nginx.conf no seu repositório.
• A verificação da distribuição (9 requisições, 3 por réplica) colada em results/lab3.md.
• O experimento de falhas (stop e pause) descrito com números.
• A tabela do rate limit.
• Varreduras com 1 e 3 réplicas para as duas cargas, as capacidades, a eficiência de escala de cada uma e o container no limite.
• Repositório com a tag lab3; quiz respondido.

Estado final

📁 boxoffice/
├──  docker-compose.yaml        # replaced: db, catalog-1..3 (no host ports), edge on port 80
├──  infra/nginx/nginx.conf     # new: reverse proxy, load balancer, rate limiter
├──  load/ratelimit.js          # new
├──  services/catalog/src/main/java/boxoffice/catalog/InstanceHeaderFilter.java   # new
└──  results/lab3.md  results/lab3-*/

Daqui em diante os clientes usam http://localhost (a borda); as réplicas não são alcançáveis a partir da sua máquina.

Próximo: Lab 4 — Gateway e identidade.