Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท CI and Cloud

k6 with Docker and Kubernetes: Distributed Load

Run k6 in Docker and Docker Compose, split one test across machines with execution segments, and use the k6 Operator TestRun resource to run distributed tests in Kubernetes.

A single k6 process is very efficient: one modest machine can often generate thousands of requests per second. Sooner or later, though, you need either repeatability (the same environment everywhere, which Docker gives you) or more load than one machine can produce (which needs distribution, for example in Kubernetes). This lesson covers both.

Honesty note. Docker and Kubernetes are not available in the in-browser runner, so commands and manifests are read-only. Runnable blocks are Node stand-ins that show the arithmetic of splitting load and a classic mistake when combining results.

k6 in Docker

Grafana publishes the image grafana/k6. Since it contains only the k6 binary, scripts are mounted or piped in:

Terminal
# Pipe the script through stdin (no volume needed)
docker run --rm -i grafana/k6 run - < script.js

# Or mount a folder
docker run --rm -v "$PWD":/scripts -e BASE_URL=https://staging.example.test \
  grafana/k6 run /scripts/script.js

Things to know:

  • Pin the tag (grafana/k6:1.0.0, not latest) so results are comparable.
  • -e passes environment variables, which the script reads with __ENV.
  • Files used with open() must exist inside the container, so mount their folder.
  • To reach a service on your host from inside the container, use host.docker.internal (Docker Desktop) or a user-defined network.

Docker Compose: app, k6 and a dashboard

Compose lets you start the system under test and the load generator together. A shortened, read-only example that sends metrics to Prometheus:

YAML
services:
  api:
    image: my-api:test
    ports: ['8080:8080']

  prometheus:
    image: prom/prometheus
    command: ['--web.enable-remote-write-receiver']
    ports: ['9090:9090']

  k6:
    image: grafana/k6
    depends_on: [api, prometheus]
    environment:
      K6_PROMETHEUS_RW_SERVER_URL: http://prometheus:9090/api/v1/write
      BASE_URL: http://api:8080
    volumes: ['./scripts:/scripts']
    command: run -o experimental-prometheus-rw /scripts/load.js

Inside the Compose network services find each other by name (http://api:8080). Run the generator on a different machine than the system under test when you can: if both share one CPU, you measure how they compete, not how the system behaves.

Why distribute a test

You need more than one load generator when:

  1. One machine's CPU or network is saturated (check CPU use and dropped_iterations).
  2. You need traffic from several regions or networks.
  3. You need more open connections or ephemeral ports than one host offers.

Before distributing, optimize: discard response bodies you do not read (discardResponseBodies: true), avoid heavy per-iteration JavaScript, and raise OS limits for open files. Many "we need 10 machines" problems are solved by these.

Execution segments

k6 can run a slice of a test. With --execution-segment, each instance runs only its fraction of the VUs and iterations, and all slices together equal the full test:

Terminal
# Four machines, each running one quarter:
k6 run --execution-segment "0:1/4"   --execution-segment-sequence "0,1/4,1/2,3/4,1" script.js
k6 run --execution-segment "1/4:1/2" --execution-segment-sequence "0,1/4,1/2,3/4,1" script.js
k6 run --execution-segment "1/2:3/4" --execution-segment-sequence "0,1/4,1/2,3/4,1" script.js
k6 run --execution-segment "3/4:1"   --execution-segment-sequence "0,1/4,1/2,3/4,1" script.js

Each instance computes its share deterministically, so 100 VUs become 25 per machine and a constant-arrival-rate of 200 iterations per second becomes 50 per machine. Rounding is handled so that nothing is lost or duplicated.

Node.js Stand-in: dividing VUs and rates across instances

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The Kubernetes operator

Running kubectl jobs by hand is clumsy. The k6 Operator adds a custom resource, TestRun, that creates the right number of runner pods, gives each its execution segment and starts them together.

First put your script in a ConfigMap, then apply a TestRun:

Terminal
kubectl create configmap load-script --from-file=load.js
YAML
apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: checkout-load
spec:
  parallelism: 4            # four runner pods, each with 1/4 of the test
  script:
    configMap:
      name: load-script
      file: load.js
  arguments: --out experimental-prometheus-rw --tag testid=checkout-w12
  runner:
    env:
      - name: BASE_URL
        value: http://checkout.staging.svc.cluster.local
    resources:
      requests: { cpu: '1', memory: 1Gi }

The operator launches an initializer pod (to validate the script and compute segments), then the runner pods, then a starter that releases them together. Observe progress with kubectl get testruns and kubectl logs on the runner pods. Because the cluster is in the same network as your service, you can test internal URLs. Remember to give runners enough CPU and place them on nodes that are not hosting the system under test.

flowchart TD
    C["kubectl apply TestRun"] --> O["k6 Operator"]
    O --> I["Initializer pod: parse script, compute segments"]
    I --> R1["Runner 1: segment 0:1/4"]
    I --> R2["Runner 2: segment 1/4:1/2"]
    I --> R3["Runner 3: segment 1/2:3/4"]
    I --> R4["Runner 4: segment 3/4:1"]
    R1 & R2 & R3 & R4 --> S["System under test"]
    R1 & R2 & R3 & R4 --> M["Shared output: Prometheus or cloud"]

The operator splits one test into segments and runs them in parallel pods.

Distributed results: the traps

When each instance runs separately, three things need care:

  1. Thresholds are evaluated per instance, on that instance's slice only, so a distributed run can pass locally while the whole system fails (or the reverse). Send all instances to a shared backend and evaluate thresholds there, or in Grafana Cloud k6, which aggregates for you.
  2. You cannot average percentiles. The mean of four p(95) values is not the p(95) of the combined data. Aggregate raw samples (or use a backend that stores them) and compute the percentile afterwards.
  3. Shared state does not exist across instances. Data returned by setup() is computed in each instance separately; unique-data logic using __VU must be coordinated through segments or through separate data partitions.
Node.js Stand-in: averaging per-instance p(95) is wrong

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you pin a Docker image tag such as grafana/k6:1.0.0?

    A new k6 release can change defaults or output; pinning keeps runs comparable and reproducible.
  2. 2. What does an execution segment do?

    Segments partition the test deterministically, so several instances together run the whole load.
  3. 3. What is wrong with averaging the p(95) values of four runner pods?

    Percentiles are not additive. You need the combined samples or a backend that merges them.
  4. 4. What does parallelism: 4 in a TestRun mean?

    The operator starts four runner pods, each with one quarter of the load.

Summary

  • grafana/k6 makes runs reproducible; mount scripts, pass env vars and pin tags.
  • Optimize one generator first, then distribute with execution segments.
  • The k6 Operator's TestRun (parallelism, script.configMap) automates distributed runs.
  • Evaluate thresholds and percentiles on combined data, not per instance.

Next: Grafana Cloud k6