The problem

The order service exposes two heavily read routes: the paginated list of orders and the detail of one order. Before adding a replica, we want to see the API under a rising load.

An improvised test lives on one laptop, then disappears; its verdict is read by eye. We want a stack small enough to be copied to stock, and a test that fails on its own.

The solution

Four files next to the service: a Compose file, a Caddyfile, a k6 script and a Foundry story. The Compose project has its own name: the development stack stays untouched.

# services/order/compose.load.yaml
name: order-load

services:
  database:
    image: postgres:18-trixie
    # ... credentials and healthcheck ...

  # Once: migrates, then fills the database.
  seed:
    build: { context: ., target: frankenphp_dev }
    command: bin/console foundry:load-fixtures load-test --append
    depends_on:
      database: { condition: service_healthy }
    volumes: ['./:/app']
    # ... environment ...

  api:
    build: { context: ., target: frankenphp_prod }
    depends_on:
      seed: { condition: service_completed_successfully }
    deploy:
      replicas: ${API_REPLICAS:-3}
      resources:
        limits: { cpus: '1', memory: 1G }
    # ... environment and healthcheck ...

  lb:
    image: caddy:2-alpine
    depends_on:
      api: { condition: service_healthy }
    ports: ['8480:80']
    volumes: ['./load/Caddyfile:/etc/caddy/Caddyfile:ro']

  k6:
    image: grafana/k6:2.2.0
    command: run /load/script.js
    environment: { BASE_URL: 'http://lb' }
    profiles: [test]
    volumes: ['./load:/load:ro']
  • seed starts from the dev image, which contains Foundry. The entrypoint of the symfony-docker template migrates the database before the command: the replicas never race on the migrations.
  • Without a limit, one replica takes the whole machine and a second one adds nothing visible. With 1 CPU each, the same curve on one then three replicas measures what they add.
  • k6 has a profile: up does not start it, run k6 does.

With reverse_proxy api:80, Caddy would only see one upstream, resolved by Docker's DNS. The dynamic a module creates one upstream per A record of the name api, so one per replica.

# services/order/load/Caddyfile
{
	auto_https off
	admin off
}

:80 {
	reverse_proxy {
		dynamic a api 80 {
			refresh 5s
		}
		lb_policy round_robin
		# Which replica answered.
		header_down X-Upstream {upstream_hostport}
	}
}

The k6 script, thresholds included:

// services/order/load/script.js
import { check, sleep } from 'k6';
import http from 'k6/http';

export const options = {
  scenarios: {
    ramp: {
      executor: 'ramping-vus',
      stages: [
        { duration: '1m', target: 50 },
        { duration: '2m', target: 50 },
        { duration: '30s', target: 0 },
      ],
    },
  },
  thresholds: {
    http_req_failed: ['rate<0.01'],
    http_req_duration: ['p(95)<800'],
    'http_req_duration{name:order-detail}': ['p(95)<300'],
    checks: ['rate>0.99'],
  },
};

export default function () {
  const page = 1 + Math.floor(Math.random() * 500);
  const list = http.get(`${__ENV.BASE_URL}/orders?page=${page}`, {
    tags: { name: 'order-list' },
  });
  check(list, { 'list is 200': (r) => r.status === 200 });

  const order = (list.json('member') || [])[0];
  if (order) {
    const detail = http.get(`${__ENV.BASE_URL}${order['@id']}`, { tags: { name: 'order-detail' } });
    check(detail, { 'detail is 200': (r) => r.status === 200 });
  }
  sleep(1);
}

The name tag groups the detail URLs under a threshold of their own. A crossed threshold makes k6, and so the moon task, exit with a non-zero code. A failed check does not change that code: the threshold on checks ties it in.

Three moon tasks, with runInCI: false, run up -d --build --wait, run --rm k6 and down -v. For stock, we copy these files, then change the story and the requests.

Everything runs on one machine: the test compares, it does not size capacity One machine: cores, memory and disk are shared compose.load.yaml k6 p(95) thresholds lb : Caddy round_robin api : 1 CPU, 1 GB api : 1 CPU, 1 GB api : 1 CPU, 1 GB PostgreSQL one database seed : run once What sets it apart from production k6 takes CPU from the replicas cpus : a cap, not a reserved core one database, synthetic data

The pitfall

This test compares two states on one machine, without saying what production will absorb.

  • One machine. The replicas share cores, memory and disk. cpus: '1' is a quota, not a reserved core: on four cores, three replicas, PostgreSQL and k6 get in each other's way.
  • The load generator shares the CPU. The k6 documentation recommends keeping 20% of the CPU idle on the load machine. Otherwise, k6 throttles itself and measures response times that are too long.
  • The database is not the production one. One instance without replicas or tuning, synthetic data, no network latency between machines.

We compare a before and an after, or one replica against three, with the same curve. Production capacity is measured elsewhere: a dedicated environment, load generators on other machines.

Sources