- Installation
- Load generators types (aka backends)
- User flow
- Adding a new load generator
- Reporting
- Developer guide
- Troubleshooting
Welcome to the Kangal - Kubernetes and Go Automatic Loader! In this section you can find information about load generators and how to write tests.
To install Kangal in your Kubernetes cluster follow the instructions from the Helm Chart page.
Currently, there are the following load generator types implemented for Kangal:
- Fake - Mock up provider used for testing purposes, not generating any load.
- JMeter - Kangal creates JMeter load test environments based on hellofresh/kangal-jmeter docker image.
- Locust - Kangal creates Locust load test environments based on official docker image locustio/locust.
ghz
- Kangal createsghz
load test environments using hellofresh/kangal-ghz docker image.- k6 - Kangal creates k6 load test environments based on official docker image grafana/k6.
JMeter is a powerful tool which can be used for different performance testing tasks.
Please read docs/jmeter/README.md for further details.
Locust is an easy to use, scriptable and scalable performance testing tool. You define the behaviour of your users in regular Python code, instead of using a clunky UI or domain specific language. This makes Locust infinitely expandable and very developer friendly.
Please read docs/locust/README.md for further details.
ghz
is a gRPC benchmarking and load testing tool.
Please read docs/ghz/README.md for further details.
k6 is an open-source load testing tool that makes performance testing easy and productive for engineering teams. k6 is free, developer-centric, and extensible. You define the behaviour of your users in regular JavaScript code.
Please read docs/k6/README.md for further details.
Read more at docs/user-flow.md.
Kangal can be easily extended by adding different load generators as backends.
-
Create a docker image that must contain an executable of a new load generator and all required scripts to run it. Docker image should exit once load test is finished and it should provide logs to stdout which will be used by Kangal Proxy.
-
Create a new backend resource definition in Kangal source code:
Reporting is an important part of load testing process. It basically contains in two parts:
- Live metrics during the running load test, Kangal Proxy scrapes logs from main job stdout container.
- Solid report generated after the end of the test.
Kangal Proxy provides an API endpoint that allows to retrieve persisted reports (/load-test/:name/report/
).
Kangal relies on report creation to be implemented in the backend.
Kangal generates a Pre-Signed URL and backend can use it to persist a report.
If the report contains multiple files it will be necessary to archive/compress into a single file.
To allow Kangal to serve the report static files it is necessary to explicitly set the file as a tar
archive with no compression and no enclosing directory, otherwise, the endpoint will just force the report download.
The script below is an example of how to properly persist to the storage.
if [[ -n "${REPORT_PRESIGNED_URL}" ]]; then
echo "=== Saving report to Object storage ==="
tar -C /path/to/reports/ -cf /tmp/report-archive.tar .
curl -X PUT -H "Content-Type: application/x-tar" -T /tmp/report-archive.tar -L "${REPORT_PRESIGNED_URL}"
fi
To start developing Kangal you need a local Kubernetes environment, e.g. minikube or docker desktop.
Note: Depending on load generator type, load test environments created by Kangal may require a lot of resources. Make sure you increased your limits for local Kubernetes cluster.
git clone https://github.com/hellofresh/kangal.git
cd kangal
kubectl apply -f charts/kangal/crds/loadtest.yaml
or just use:
make apply-crd
go mod vendor
make verify-codegen
In case of message "is out of date", it's necessary to run:
make update-codegen
Attention: Changes to generated code could lead to the changes in CRDs and possibly break backwards compatibility
make build
export AWS_BUCKET_NAME=YOUR_BUCKET_NAME # name of the bucket for saving reports
export AWS_ENDPOINT_URL=YOUR_BUCKET_ENDPOINT # storage connection parameter
export AWS_DEFAULT_REGION=YOUR_AWS_REGION # storage connection parameter
export KANGAL_PROXY_URL=http://localhost:8080 # used to persist reports
For the full list of possible environment variables check Kangal environment variables
WEB_HTTP_PORT=8888 ./kangal controller --kubeconfig=$KUBECONFIG
WEB_HTTP_PORT=8080 ./kangal proxy --kubeconfig=$KUBECONFIG
Read more at docs/troubleshooting.md.