Injecting faults with xk6-disruptor on Grafana Labs

xk6-disruptor first steps

Mon, 21 Sep 2026 15:16:28 +0000

xk6-disruptor first steps

xk6-disruptor is an extension that adds fault injection capabilities to k6.

It provides a Javascript API to inject faults such as errors and delays into HTTP and gRPC requests served by selected Kubernetes Pods or Services.

import { ServiceDisruptor } from 'k6/x/disruptor';

export default function () {
  // Create a new disruptor that targets a service
  const disruptor = new ServiceDisruptor('app-service', 'app-namespace');

  // Disrupt the targets by injecting delays and faults into HTTP request for 30 seconds
  const fault = {
    averageDelay: '500ms',
    errorRate: 0.1,
    errorCode: 500,
  };
  disruptor.injectHTTPFaults(fault, '30s');
}

Next steps

Explore the fault injection API

See step-by-step examples.

Visit the interactive demo environment.

Learn the basics of using the disruptor in your test project:

Requirements

Mon, 21 Sep 2026 15:16:28 +0000

Requirements

The xk6-disruptor is a k6 extension. To use it in a k6 test script, you need to bundle a k6 extension that includes the disruptor. Refer to the Installation section for instructions on how to get this custom build.

xk6-disruptor needs to interact with the Kubernetes cluster on which the application under test is running. To do so, you must have the credentials to access the cluster in a kubeconfig file. Ensure that this file is pointed to by the KUBECONFIG environment variable or that it is located at the default location, $HOME/.kube/config.

Note
xk6-disruptor requires Kubernetes version 1.23 or higher

xk6-disruptor requires the grafana/xk6-disruptor-agent image for injecting the disruptor agent into the disruption targets. Kubernetes clusters can be configured to restrict the download of images from public repositories. You need to ensure this image is available in the cluster where the application under test is running. Additionally, the xk6-disruptor-agent must run with network access privileges. Kubernetes clusters can be configured to restrict the privileges of containers. If you find an error similar to the following when using the xk6-disruptor, contact your cluster administrator and request the necessary privileges.

ERROR[0000] error creating PodDisruptor: pods “nginx” is forbidden: violates PodSecurity “baseline:latest”: non-default capabilities (container “xk6-agent” must not include “NET_ADMIN”, “NET_RAW” in securityContext.capabilities.add)

You also need to ensure your test application is accessible from the machine where the tests run. Refer to Expose your application section for instructions on how to make your application available from outside the Kubernetes cluster.

Installation

Mon, 21 Sep 2026 15:16:28 +0000

Installation

xk6-disruptor is a k6 extension. You have to run a k6 version built with the disruptor extension to use the disruptor APIs in your k6 tests.

The following sections explain the different options to get this custom binary.

Download a release binary

The quickest way to get started is to download a release binary from GitHub.

Build from source

You can also use xk6 to build a k6 binary.

To learn more about xk6, refer to Build a k6 binary using Go.

To build the k6 binary with the xk6-disruptor extension:

Ensure you have Go 1.19 and Git installed.
Run the following commands in a terminal:

# Install xk6
go install go.k6.io/xk6/cmd/xk6@latest

# Clone the xk6-disruptor code
git clone https://github.com/grafana/xk6-disruptor.git
cd xk6-disruptor

# Build the custom binary
xk6 build --output xk6-disruptor --with github.com/grafana/xk6-disruptor=.

xk6 will create the xk6-disruptor binary in the current working directory.

Expose your application

Mon, 21 Sep 2026 15:16:28 +0000

Expose your application

To access your application from the test scripts, you must assign it an external IP in the cluster where it’s running. How you do this depends on the platform you use to deploy the application. The following sections explain the different approaches.

Using port-forwarding

kubectl’s port-forward command allows accessing applications running in a Kubernetes cluster using a local port.

For example, the following command will make my-service’s port 80 accessible as localhost:8080:

kubectl port-forward svc/my-service 8080:80
Forwarding from 127.0.0.1:8080 -> 80

Limitations using port forwarding

To be able to inject faults, xk6-disruptor must install an agent on each target that intercepts the requests and applies the desired disruptions. This process requires any existing connection to the targets to be redirected to the agent.

Due to an existing bug in kubectl, the process of installing the disruptor can potentially break the port forwarding. Notice that this issue happens only if the faults are injected in the service that is exposed using port forward. If the faults are injected in another service not exposed by port-forwarding, there shouldn’t be any issue.

Until this issue is solved in kubectl, tests using port forwarding to access a service should ensure the agent is installed in the targets before any traffic is sent by the test.

The simplest way to accomplish this is to ensure the scenario that executes the load (#2) starts after the scenario that injects the faults (#1):

    scenarios: {
        disrupt: {   // #1 inject faults
            executor: 'shared-iterations',
            iterations: 1,
            vus: 1,
            exec: "disrupt",
            startTime: "0s",
        },
        load: {   // #2 execute load
            executor: 'constant-arrival-rate',
            rate: 100,
            preAllocatedVUs: 10,
            maxVUs: 100,
            exec: "default",
            startTime: '20s',  // give time for the agents to be installed
            duration: "30s",
        }
     }

As a LoadBalancer service

A service of type LoadBalancer receives an external IP from an external load-balancer provider. How you configure the load balancer depends on the your cluster’s deployment platform and configuration. The following sections provide guidelines to expose your application when running in common development environments. If your cluster is deployed in a public cloud, check your cloud provider documentation.

If the service that you want your tests to access is not defined as a load balancer, you can change the service type with the following command. The service will then receive an external IP.

kubectl -n <name space> patch svc <service name> -p '{"spec": {"type": "LoadBalancer"}}'

kubectl -n <name space> patch svc <service name> -p '{\"spec\": {\"type\": \"LoadBalancer\"}}'

You can retrieve the external IP address and store it in an environment variable (SVC_IP in this example) using the following command:

SVC_IP=$(kubectl -n <name space>  get svc <service name> --output jsonpath='{.status.loadBalancer.ingress[0].ip}')

$Env:SVC_IP=$(kubectl -n <name space>  get svc <service name> --output jsonpath='{.status.loadBalancer.ingress[0].ip}')

Configuring a LoadBalancer in Kind

Kind is a tool to run local Kubernetes clusters using a Docker container to emulate nodes. You can use kind for local development or CI. Services deployed in a kind cluster can be exposed to be accessed from the host machine using metallb as a load balancer.

Configuring a LoadBalancer in Minikube

Minikube implements a local Kubernetes cluster that supports different technologies to virtualize the cluster’s infrastructure, such as containers, VMs or bare metal.

Minikube’s tunnel command runs as a process, creating a network route on the host to the service CIDR of the cluster. It uses the cluster’s IP address as a gateway. The tunnel command exposes the external IP directly to any program that is running on the host operating system.

minikube tunnel

How xk6-disruptor works

Mon, 21 Sep 2026 15:16:28 +0000

How xk6-disruptor works

xk6-disruptor consists of two main components:

The xk6-disruptor extension provides a Javascript API for injecting faults into a target system using the xk6-disruptor-agent as a backend. This API is built around a collection of disruptors. Each disruptor targets a type of component in the system (for example Pods or cluster Nodes).
The xk6-disruptor-agent injects faults into the target system where it runs. It is provided as an Docker image that you can pull from the xk6-disruptor repository.

The xk6-disruptor extension installs the agent in the target and sends commands to inject the desired faults. How this happens depends on the type of disruptor, as described in the following sections.

PodDisruptor

The following diagram shows how PodDisruptor works:

The PodDisruptor selects the target pods based on the selector attributes defined in the constructor
The PodDisruptor attaches the xk6-disruptor-agent to each of the target pods
When a fault is injected (e.g. calling the injectHTTPFaults) the PodDisruptor sends a command to the agents to inject the fault in their respective pods

ServiceDisruptor

The ServiceDisruptor works as a wrapper around a PodDisruptor, which targets the pods that back the service.

The ServiceDisruptor uses the definition of the service specified in the constructor to create a pod selector that matches the pods that back the service.
The ServiceDisruptor creates a PodDisruptor using this pod selector.
The PodDisruptor installs the agent in the target pods.

From this point, the PodDisruptor works as described before.

xk6-disruptor API

Mon, 21 Sep 2026 15:16:28 +0000

xk6-disruptor API

The xk6-disruptor API is organized around disruptors that affect specific targets such as pods or services. These disruptors can inject different types of faults on their targets.

Class	Description
PodDisruptor	Targets the Pods that match selection attributes such as labels.
ServiceDisruptor	Targets the Pods that back a Kubernetes Service

xk6-disruptor examples

Mon, 21 Sep 2026 15:16:28 +0000

xk6-disruptor examples

In this section, we present some examples of using the xk6-disruptor extension to introduce faults in k6 tests.

To follow the instructions of the examples, check first the system under test meets the requirements to receive faults, in particular:

You have configured the credentials to access the Kubernetes cluster.
This cluster exposes the service using an external IP.