Responsive

A Guide to Scalable and Heavy Load Testing with k6 + Testkube

Published
July 20, 2025
Bruno Lopes
Product Leader
Testkube

Table of Contents

Run High-Scale k6 Tests with Testkube

Unlock Better Testing Workflows in Kubernetes — Try Testkube for Free

Subscribe to our monthly newsletter to stay up to date with all-things Testkube.

You have successfully subscribed to the Testkube newsletter.
You have successfully subscribed to the Testkube newsletter.
Oops! Something went wrong while submitting the form.
Last updated
July 19, 2025
Bruno Lopes
Product Leader
Testkube
Share on X
Share on LinkedIn
Share on Reddit
Share on HackerNews
Copy URL

Table of Contents

Testkube Distributed k6 Testing TL;DR

TL;DR

Testkube Distributed k6 Load Testing

  • 1
    Testkube simplifies distributed k6 load testing compared to the k6 operator by providing flexible test triggering, Git integration, and easier configuration without requiring deep Kubernetes expertise
  • 2
    Creating distributed tests is straightforward - use Testkube's wizard to select the "Distributed k6" example template, which automatically generates the YAML configuration for parallel test execution
  • 3
    Tests run in parallel across multiple workers - you can configure the number of virtual users, test duration, and worker count through parameters, with each worker handling a segment of the total load
  • 4
    Built-in reporting and artifacts - Testkube automatically collects logs and generates HTML reports for each worker, making it easy to analyze performance results from the distributed test run
  • 5
    Production-ready setup requires a Testkube account, Kubernetes cluster (like Minikube), and the Testkube agent configured on your cluster to orchestrate the distributed load testing workflow

Every team aspires for their application to be flexible, scalable, and capable of handling user requests efficiently. While functional testing validates the application’s features, load testing assesses how the application performs under stress.

Modern tools have simplified functional testing, but conducting distributed load tests to evaluate an application’s resiliency remains complex. It requires the ability to adjust tests to simulate production-like scenarios dynamically.

In our previous post, we discussed the benefits of using Testkube over the k6 operator for scaling load testing. In this post, we’ll cover step-by-step how to scale your k6 load tests using Testkube to ensure your application can handle heavy loads seamlessly.

Distributed K6 Testing with Testkube

We discussed distributed load testing, k6, and how the k6 operator stacks up against Testkube in this blog post. Let us apply what we have learned and create a distributed k6 test using Testkube. We’ll create a Test workflow for running distributed k6 load tests and configure it to run in parallel. 

Pre-requisites

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

We've created a video tutorial that walks you through the process. This video provides a visual guide to creating and running your k6 distributed test workflow using Testkube. You can watch it for a quick overview or follow along as you implement the steps yourself.

Creating a Test Workflow

Navigate to the Test Workflows tab and click on “Add a new test workflow”

This will provide you with three 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 - use with existing workflows.
  • Import from yaml - import your own Test Workflow.

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 will show a sample yaml code that will create a distributed k6 test. We’ll look at the yaml file at the end of this document.

Click on Create to create the Test Workflow.

Executing Test Workflow

Now that the Test Workflow is ready, click “Run Now” to execute the workflow. It will prompt you to provide values for parameters like the duration, number of virtual users, and workers. Provide the values as per your requirement and click the Run button.

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 using Testkube. To take advantage of test workflows more, you can create custom workflows and import them to Testkube.

Let us now take a look at the test definition that was generated for the Test Workflow

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/executor-tests/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/executor-tests
       env:
       - name: K6_SYSTEM_ENV
         value: K6_SYSTEM_ENV_value
       - name: K6_WEB_DASHBOARD
         value: "true"
       - name: K6_WEB_DASHBOARD_EXPORT
         value: /data/k6-test-report.html
       resources:
         requests:
           cpu: 128m
           memory: 128Mi
     paused: true
     run:
       image: grafana/k6:0.49.0
       shell: |
         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 }}
     artifacts:
       workingDir: /data
       paths:
       - '*.html'
status: {}

In the above file:

  • The configuration specs define the number of workers, virtual users, and duration of the test. The document also specifies the environment variables for k6.
  • The test source is a file in a GitHub repository. Refer to the k6 test referred to in this definition.
  • Resource limits are provided for CPU and memory, along with the image details. 
  • Test execution command is provided along with artifacts configuration to collect the logs.

Summary

There’s no second thought that load testing is critical to test the resilience of your application. Distributed load testing provides you with a more realistic and production-like environment. Tools like k6 make load testing simpler. 

Regarding Kubernetes, Leveraging 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 in Testkube using other testing tools. Feel free to post a note in our active Slack community if you struggle with anything.

Top 5 Distributed k6 Testing with Testkube FAQs

Distributed k6 Testing with Testkube FAQs

Essential questions about scalable load testing in Kubernetes

Distributed load testing with k6 involves running performance tests concurrently across multiple instances (workers) to simulate high traffic loads that would be impossible to generate from a single machine. In Kubernetes environments, this approach leverages the orchestration platform's ability to scale and manage multiple test pods.

How it works in Kubernetes:

  • Parallel execution: Multiple k6 pods run simultaneously across different nodes in the cluster
  • Load distribution: Each worker handles a portion of the total virtual users and requests
  • Orchestration tools: Platforms like Testkube coordinate test execution and collect results from all workers
  • Resource utilization: Tests can leverage the full compute capacity of the Kubernetes cluster
  • Realistic simulation: Distributed testing provides production-like load patterns and network conditions

This approach enables testing at scales that closely mirror real-world traffic while taking advantage of Kubernetes' native scaling and resource management capabilities.

Testkube significantly simplifies distributed k6 testing by providing a more user-friendly approach compared to the k6 operator, which requires deeper Kubernetes expertise and manual configuration.

Key improvements Testkube offers:

  • Simplified setup: UI/CLI wizard guides users through test configuration without requiring YAML expertise
    • Intuitive web interface for test creation and management
    • Command-line tools for automation and CI/CD integration
  • Git integration: Direct connection to version control systems for test script management
    • Automatic test execution on code changes
    • Version tracking and rollback capabilities
  • Parameter configuration: Easy-to-use forms and interfaces for setting test parameters
    • No need to manually edit complex Kubernetes manifests
    • Template-based configuration with sensible defaults
  • Built-in reporting: Comprehensive dashboards and result visualization
    • Real-time test monitoring and progress tracking
    • Historical data comparison and trend analysis
  • Reduced complexity: Abstracts away Kubernetes-specific details while maintaining full functionality

To successfully run distributed k6 tests with Testkube, you need several components properly configured and connected:

  • Testkube account: Sign up for a Testkube cloud account or set up an on-premises installation
    • Access to the Testkube dashboard and API
    • User authentication and workspace setup
  • Kubernetes cluster: A functioning cluster with sufficient resources
    • Local development: Minikube, kind, or Docker Desktop
    • Cloud platforms: EKS, GKE, AKS, or managed Kubernetes services
    • Adequate CPU and memory for distributed test execution
  • Testkube agent: The agent must be installed and properly configured in your cluster
    • Agent deployment using Helm charts or kubectl
    • Network connectivity between agent and Testkube cloud
    • Proper RBAC permissions for test execution
  • Additional requirements:
    • Container registry access for custom test images (if needed)
    • Network connectivity to target applications
    • Storage for test artifacts and results (optional but recommended)

Testkube provides streamlined configuration options for parallel k6 test execution through its "Distributed k6" workflow templates and intuitive parameter settings.

Configuration process:

  • Use the Distributed k6 template: Testkube offers pre-built workflow examples
    • Select the "Distributed k6" option when creating a new test
    • Choose from sample YAML templates with common configurations
  • Key parameters to configure:
    • parallelism: Number of worker pods to run simultaneously
    • vus: Virtual users per worker (total VUs = parallelism × vus)
    • duration: Test execution time (e.g., "5m", "30s")
    • iterations: Total number of iterations to distribute across workers
  • Example configuration:
    • 4 workers × 25 VUs each = 100 total virtual users
    • Test duration of 10 minutes across all workers
    • Automatic result aggregation from all pods
  • Advanced options:
    • Resource limits and requests per worker pod
    • Node affinity and pod distribution strategies
    • Custom environment variables and secrets

The platform handles the complexity of distributing the load and coordinating execution across multiple Kubernetes pods automatically.

Testkube provides comprehensive result analysis capabilities that automatically collect and aggregate data from all distributed test workers, making it easy to understand overall performance and identify issues.

Result collection and analysis features:

  • Automatic aggregation: Testkube automatically collects logs and metrics from all worker pods
    • Centralized data collection without manual intervention
    • Real-time progress monitoring during test execution
  • Individual worker reports: Access detailed HTML reports for each worker
    • Per-worker performance metrics and statistics
    • Individual response time distributions and error rates
    • Granular analysis of load distribution effectiveness
  • Artifacts tab access: All reports and logs are available in the dedicated Artifacts section
    • Downloadable HTML reports for offline analysis
    • Raw log files for detailed debugging
    • JSON result files for custom analysis tools
  • Dashboard visualization: Built-in charts and graphs for quick insights
    • Response time trends and percentile analysis
    • Throughput and error rate visualization
    • Resource utilization metrics across workers
  • Historical comparison: Track performance trends over time and compare test runs for regression analysis

This comprehensive approach enables both high-level performance overview and deep-dive analysis for troubleshooting and optimization.

About Testkube

Testkube is a test execution and orchestration framework for Kubernetes that works with any CI/CD system and testing tool you need. It empowers teams to deliver on the promise of agile, efficient, and comprehensive testing programs by leveraging all the capabilities of K8s to eliminate CI/CD bottlenecks, perfecting your testing workflow. Get started with Testkube's free trial today.