kangal

Kangal - Automatic loader

Run performance tests in Kubernetes cluster with Kangal.

Table of content

• 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

Why Kangal?

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.

Key features

• 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

How it works

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.

Supported backends

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.

Architectural diagram

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

Components

LoadTest Custom Resource

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.

Kangal Proxy

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.

Kangal Controller

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

Quickstart guide

This tutorial will guide through Kangal installation process and usage.

Installing using helm

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.

Creating first LoadTest

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

Documentation

Read more at docs/index.md.

Contributing

Please check the contribution guide before opening a PR.

Support

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