Distributed k6 Load Testing with Testkube

Distributed k6 load testing with Testkube runs one k6 test across several parallel workers inside your Kubernetes cluster, so you can generate heavy, production-like load without managing the k6 Operator. This guide shows how to create, run and review a distributed k6 Test Workflow step by step.

Every team wants its application to be flexible, scalable and able to handle user requests efficiently. Functional testing validates an application’s features, while load testing assesses how the application performs under stress. Modern tools have simplified functional testing, but distributed load tests that simulate production-like traffic remain complex to set up and scale.

In a previous post, we compared the k6 Operator and Testkube for load testing. In this post, we cover step by step how to scale your k6 load tests with Testkube so your application can handle heavy loads.

How Do You Run Distributed k6 Tests with Testkube?

You run distributed k6 tests in Testkube with a Test Workflow that splits one k6 script across parallel workers in your cluster. Our previous post covered distributed load testing, k6 and how the k6 Operator stacks up against Testkube. Now let’s apply what we learned and create a Test Workflow that runs distributed k6 load tests in parallel.

Prerequisites

• A Testkube account.
• A Kubernetes cluster (we’re using a local Minikube cluster).
• A Testkube Runner configured on the cluster.

Once the prerequisites are in place, you should have a target Kubernetes cluster ready with a Testkube Runner configured.

We’ve created a video tutorial that walks you through the process. It’s a visual guide to creating and running your distributed k6 Test Workflow with Testkube. Watch it for a quick overview, or follow along as you implement the steps yourself.

How Do You Create a Distributed k6 Test Workflow?

You create a distributed k6 Test Workflow in the Testkube Dashboard by starting from the built-in Distributed k6 example. Navigate to the Test Workflows tab and click “Add a new test workflow”.

This gives you four options:

• Create from Wizard: use the wizard to create a Test Workflow.
• Start from an example: use existing k6, Cypress and Playwright examples.
• Combine existing workflows: build a new workflow from existing ones.
• Import from YAML: import your own Test Workflow definition.

We’ll choose the “Start from an example” option to create this workflow. In the examples tab, choose “Parallel Execution” and then select “Distributed k6”. This shows a sample YAML definition that creates a distributed k6 test. We’ll look at the YAML file at the end of this post.

Click Create to save the Test Workflow.

How Do You Run the Test Workflow and Review the Results?

Now that the Test Workflow is ready, click “Run Now” to execute it. You’ll be prompted for parameter values such as the test duration, number of virtual users and number of workers. Enter the values you need and click Run.

The Test Workflow will start executing based on the parameter values that you’ve provided. 

Based on the number of workers provided, you can see that k6 load tests are running in parallel. You can click on any of those to view the detailed steps.

Navigate to the “Artifacts” tab to check the logs and reports generated from the test. You’ll see that logs and reports are generated for each worker. Click on any of the reports to view them in a new tab.

Below is what a typical k6 distributed test report looks like.

This was a simple demo of creating and executing distributed k6 load tests with Testkube. To get more out of Test Workflows, you can create custom workflows and import them into Testkube.

What Does the Distributed k6 Test Workflow YAML Look Like?

The Distributed k6 example generates the Test Workflow definition below. It reflects the current version of the example in the Testkube docs, so it may differ slightly from the video.

kind: TestWorkflow
apiVersion: testworkflows.testkube.io/v1
metadata:
  name: distributed-k6
  namespace: testkube
  labels:
    docs: example
spec:
  config:
    duration:
      type: string
      default: 5s
    vus:
      type: integer
      default: 10
    workers:
      type: integer
      default: 3
  content:
    git:
      uri: https://github.com/kubeshop/testkube
      paths:
        - test/k6/k6-smoke-test.js
  steps:
    - name: Run test
      parallel:
        count: config.workers
        transfer:
          - from: /data/repo
        use:
          - name: distribute/evenly
        container:
          workingDir: /data/repo/test/k6
          env:
            - name: K6_SYSTEM_ENV
              value: K6_SYSTEM_ENV_value
            - name: K6_WEB_DASHBOARD
              value: "true"
            - name: K6_WEB_DASHBOARD_EXPORT
              value: /data/artifacts/k6-test-report.html
          resources:
            requests:
              cpu: 128m
              memory: 128Mi
        paused: true
        run:
          image: grafana/k6:0.49.0
          shell: |
            mkdir -p /data/artifacts
            k6 run k6-smoke-test.js \
              -e K6_ENV_FROM_PARAM=K6_ENV_FROM_PARAM_value \
              --vus {{ config.vus }} \
              --duration {{ shellquote(config.duration) }} \
              --execution-segment {{ index }}/{{ count }}:{{ index + 1 }}/{{ count }} \
              --summary-export /data/artifacts/summary-worker-{{ index + 1 }}.json
        artifacts:
          workingDir: /data/artifacts
          paths:
            - "*.html"
            - "*.json"

In this file:

• The config section defines the test duration, number of virtual users and number of workers, with defaults you can override at run time.
• The content section pulls the k6 test script from a GitHub repository.
• The parallel step creates one k6 worker per configured worker, spreads the workers evenly across nodes and keeps them paused until all of them are ready.
• Each worker requests CPU and memory, sets the environment variables for k6 and runs the grafana/k6 image with its own execution segment.
• The artifacts section collects the HTML report and the per-worker JSON summaries.

Summary

Load testing is critical for checking the resilience of your application. Distributed load testing gives you a more realistic, production-like environment, and tools like k6 make load testing simpler.

On Kubernetes, combining k6 and Testkube can significantly enhance distributed load testing. While the k6 Operator offers robust automation, it requires deep Kubernetes expertise. Testkube simplifies the process with flexible test triggering, Git integration, distributed parameterization and support for provisioning dependent services.

Get started with Testkube today, or visit the Testkube documentation to learn more about running distributed tests with other testing tools. If you get stuck, post a note in our active Slack community.

Frequently Asked Questions

{{banner-get-started}}