Skip to content

Latest commit

 

History

History
160 lines (109 loc) · 6.23 KB

index.md

File metadata and controls

160 lines (109 loc) · 6.23 KB
Raw

Kangal

Table of content

Welcome to the Kangal - Kubernetes and Go Automatic Loader! In this section you can find information about load generators and how to write tests.

Installation

To install Kangal in your Kubernetes cluster follow the instructions from the Helm Chart page.

Load generator types (aka backends)

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 creates ghz load test environments using hellofresh/kangal-ghz docker image.
  • k6 - Kangal creates k6 load test environments based on official docker image grafana/k6.

JMeter

JMeter is a powerful tool which can be used for different performance testing tasks.

Please read docs/jmeter/README.md for further details.

Locust

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

ghz is a gRPC benchmarking and load testing tool.

Please read docs/ghz/README.md for further details.

k6

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.

User flow

Read more at docs/user-flow.md.

Adding a new load generator

Kangal can be easily extended by adding different load generators as backends.

Requirements for adding a new load generators

  1. 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.

  2. Create a new backend resource definition in Kangal source code:

Reporting

Reporting is an important part of load testing process. It basically contains in two parts:

  1. Live metrics during the running load test, Kangal Proxy scrapes logs from main job stdout container.
  2. 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.

Persisting reports

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

Developer guide

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.

1. Clone the repo locally

git clone https://github.com/hellofresh/kangal.git
cd kangal

2. Create required Kubernetes resource LoadTest CRD in your cluster

kubectl apply -f charts/kangal/crds/loadtest.yaml

or just use:

make apply-crd

3. Get project dependencies

go mod vendor

4. Verify changes in generated code

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

5. Build Kangal binary

make build

6. Set the environment variables

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

7. Run both Kangal proxy and controller

WEB_HTTP_PORT=8888 ./kangal controller --kubeconfig=$KUBECONFIG
WEB_HTTP_PORT=8080 ./kangal proxy --kubeconfig=$KUBECONFIG

Troubleshooting

Read more at docs/troubleshooting.md.