Run performance tests in Kubernetes cluster with Kangal.

• Why Kangal?
• Key features
• How it works
• Supported backends
• Architectural diagram
• Components
  • LoadTest Custom Resource
  • Kangal Proxy
  • Kangal Controller
• Quickstart guide
  • Installing using helm
  • Creating first LoadTest
• Documentation
• Contributing
• Support

In Kangal project, the name stands for "Kubernetes and Go Automatic Loader". But originally Kangal is the breed of a shepherd dog. Let the smart and protective dog herd your load testing projects.

With Kangal, you can spin up an isolated environment in a Kubernetes cluster to run performance tests using different load generators.

• create an isolated Kubernetes environment with an opinionated load generator installation
• run load tests against any desired environment
• monitor load tests metrics in Grafana
• save the report for the successful load test
• clean up after the test finishes

Kangal application uses Kubernetes Custom Resources.

LoadTest custom resource (CR) is a main working entity. LoadTest custom resource definition (CRD) can be found in charts/kangal/crds/loadtest.yaml.

Kangal application contains two main parts:

• Proxy to create, delete and check load tests and reports via REST API requests
• Controller to operate with LoadTest custom resource and other Kubernetes entities.

Kangal also uses S3 compatible storage to save test reports.

Currently, there are the following load generator types implemented for Kangal:

• Fake
• JMeter
• Locust
• ghz
• k6

Read more about each of them in docs/index.md.

The diagram below illustrates the workflow for Kangal in Kubernetes infrastructure.

A new custom resource in the Kubernetes cluster which contains requirements for performance testing environments.

More info about the Custom Resources in official Kubernetes documentation.

Provides the following HTTP methods for /load-test endpoint:

• POST - allowing the user to create a new LoadTest
• GET - allowing the user to see information (status/logs/report) for specific LoadTest and get an overview for all the currently existing loadtests
• DELETE - allowing the user to stop and delete existing LoadTest

The Kangal Proxy is documented using the OpenAPI Spec.

If you prefer to use Postman you can also import openapi.json file into Postman to create a new collection.

The component is responsible for managing all the aspects of the performance testing process.

This tutorial will guide through Kangal installation process and usage.

First, add the repository to Helm:

helm repo add kangal https://hellofresh.github.io/kangal

Now, install the chart using the following command:

helm install kangal kangal/kangal

That's it, Kangal should be installed, check if is all correct by running:

$ kubectl get pods
NAME                                 READY   STATUS    RESTARTS   AGE
kangal-controller-588677b854-r9qcs   1/1     Running   0          44s
kangal-openapi-ui-7c5dd8997c-jj4mk   1/1     Running   0          44s
kangal-openapi-ui-7c5dd8997c-vgm8c   1/1     Running   0          44s
kangal-proxy-7d95c9d65-6t44b         1/1     Running   0          44s
kangal-proxy-7d95c9d65-75dv4         1/1     Running   0          44s

$ kubectl get crd
NAME                              CREATED AT
loadtests.kangal.hellofresh.com   2020-10-05T13:22:59Z

For more information about the Helm Chart check charts/kangal/README.md.

To run a LoadTest you first need to find Kangal proxy endpoint. Use this command:

$ kubectl get ingress
NAME                HOSTS                           ADDRESS     PORTS   AGE
kangal-openapi-ui   kangal-openapi-ui.example.com   localhost   80      5m48s
kangal-proxy        kangal-proxy.example.com        localhost   80      5m48s

This is assuming you have a properly configured Ingress Controller. If it is not the case you can use Port Forwarding.

With this information, you are now able to do a request to create the first load test. Let's start by downloading an example JMeter test and POST it to Kangal proxy.

$ curl -s -O https://raw.githubusercontent.com/hellofresh/kangal/master/examples/constant_load.jmx
$ curl \
    -F "distributedPods=1" \
    -F "testFile=@constant_load.jmx" \
    -F "type=JMeter" \
    http://${KANGAL_PROXY_ADDRESS}/load-test

{
    "type": "JMeter",
    "distributedPods": 1,
    "loadtestName": "loadtest-dunking-hedgehog",
    "phase": "creating",
    "hasEnvVars": false,
    "hasTestData": false
}

Your first load test was created successfully, in this example with the name loadtest-dunking-hedgehog.

Check the load status with:

curl http://${KANGAL_PROXY_ADDRESS}/load-test/loadtest-dunking-hedgehog

{
    "type": "JMeter",
    "distributedPods": 1,
    "loadtestName": "loadtest-dunking-hedgehog",
    "phase": "running",
    "hasEnvVars": false,
    "hasTestData": false
}

Kangal Controller will automatically create a namespace for your load test and deploy the backend (in this case JMeter), check that by running:

$ kubectl get namespaces
NAME                        STATUS   AGE
...
loadtest-dunking-hedgehog   Active   3s

And you can check if the Pods started correctly using:

$ kubectl get pods --namespace=loadtest-dunking-hedgehog
NAME                    READY   STATUS    RESTARTS   AGE
loadtest-master-f6xpb   1/1     Running   0          18s
loadtest-worker-000     1/1     Running   0          22s

Read more at docs/index.md.

Please check the contribution guide before opening a PR.

If you need support, start with the troubleshooting guide, and work your way through the process that we've outlined.