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']
-
seedstarts 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.
-
k6has a profile:updoes not start it,run k6does.
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.
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
- k6, Thresholds, ramping-vus, URL grouping, Running large tests and releases (2.2.0: August 10, 2026).
- Caddy, reverse_proxy, global options and placeholders.
- Docker, deploy, services, profiles, Compose networking and resource constraints.
-
Foundry,
fixtures
and
--append; symfony-docker, entrypoint; API Platform,hydra:prefix; moon,runInCI. - Lychen, pull request 270: an open-source implementation of this load-test stack, in a moon monorepo.