The purpose of this repository is to offer a step-by-step guide for running xk6-disruptor in a local development environment using demo applications.

You can also try this demos on an interactive environment on Killercoda. We'll take care of setting up Kubernetes and the demo applications for you so you can focus on learning the basics of xk6-disruptor.

If you prefer to run the demo entirely on your local machine, you can find instructions on how to proceed below.

This tutorial assumes that you are familiar with Kubernetes concepts such as deploying applications and exposing them using services.

Even when will provide all the required commands in this tutorial, it would also be convenient if you have some familiarity with using kubectl for managing applications in Kubernetes.

⚠️ The demo has been tested on Linux and Windows 11 - using a Windows Terminal. It might not work with other OS.

The Socks-shop application implements a fully functional e-Commerce site that allows users to register, browse the catalog, and buy items. It follows a polyglot microservices-based architecture shown in the figure below. Each microservice has its own API that can be accessed directly using its corresponding Kubernetes service. The front-end service works as a backend for the web interface but also exposes the APIs of other services, working as a kind of API gateway.

You can try this demo on an interactive environment on Killercoda.

See Socks Shop demo for detailed instructions for installing this application and testing HTTP fault injection in this application

Online Boutique is a cloud-first microservices demo application. The application is a web-based e-commerce app where users can browse items, add them to the cart, and purchase them. Online Boutique consists of an 11-tier microservices application.

See Online Boutique demo for instructions for installing this application and testing gRPC fault injection in this application.

xk6-disruptor is a k6 extension. To use it in a k6 test script, it is necessary to use a custom build of k6 that includes it. You can get the binaries for different platforms from the xk6-disruptor github repository. Refer to the Installation Guide for more information.

The rest of this tutorial assumes xk6-disruptor binary is available in the system path. In other words, you can invoke it just by typing xk6-disruptor. If this is not the case, you will have to modify the commands in this tutorial accordingly.

For the setup, you will also need the kubectl tool.

Follow official documentation depending on your operating system.

For this demo, we will be using a local Kubernetes cluster deployed using Kind. Kind is a tool to run local Kubernetes clusters using Docker containers to emulate nodes.

Follow the official documentation depending on your operating system.

Create a local cluster with a name demo using the config file provided at manifests\kind-config.yaml. The resulting cluster will be configured to use the host port 38080 to access the ingress controller (see setup ingress below).

kind create cluster --name demo --config setup/kind-config.yaml

Output:

Creating cluster "demo" ...
 ✓ Ensuring node image (kindest/node:v1.24.0) 🖼
 ✓ Preparing nodes 📦  
 ✓ Writing configuration 📜 
 ✓ Starting control-plane 🕹️ 
 ✓ Installing CNI 🔌 
 ✓ Installing StorageClass 💾 
Set kubectl context to "kind-demo"
You can now use your cluster with:

kubectl cluster-info --context kind-demo

Thanks for using kind! 😊

If you get an error message with the reason Bind for 0.0.0.0:38080 failed: port is already allocated, it means this port is already in use by another application. You can change the ports used by the cluster editing the port mapping section in the manifests/kind-config.yaml file. Remember the port used as you will need it later for accessing the application.

We will install the nginx ingress controller to expose services to the host machine:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml

Output (some omitted for brevity):

namespace/ingress-nginx created
serviceaccount/ingress-nginx created
serviceaccount/ingress-nginx-admission created
...

The xk6-disruptor needs to interact with the Kubernetes cluster on which the application is running. To do so, you must have the credentials to access the cluster in a kubeconfig file.

Use the following command to set this configuration:

kind export kubeconfig --name demo

Output:

Set kubectl context to "kind-demo"

See Socks Shop demo for detailed instructions for installing this application and testing HTTP fault injection in this application

See Online Boutique demo for instructions for installing this application and testing gRPC fault injection in this application.

Learn more about k6 and load testing.