Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hellofresh/kangal
Run performance tests in Kubernetes cluster with Kangal
https://github.com/hellofresh/kangal
kangal open-source
Last synced: 3 days ago
JSON representation
Run performance tests in Kubernetes cluster with Kangal
- Host: GitHub
- URL: https://github.com/hellofresh/kangal
- Owner: hellofresh
- License: apache-2.0
- Created: 2020-09-04T11:11:05.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-04T01:52:11.000Z (7 months ago)
- Last Synced: 2024-04-04T11:32:14.969Z (7 months ago)
- Topics: kangal, open-source
- Language: Go
- Homepage:
- Size: 4.96 MB
- Stars: 157
- Watchers: 158
- Forks: 25
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-jmeter - kangal - Kubernetes and Go Automatic Loader solution to run performance tests in Kubernetes cluster using multiple load generators. (Distributed Testing / Tutorials & Demo)
- awesome-locust - kangal - Run performance tests in Kubernetes cluster using multiple load generators. (Tools / Distributed)
README
# Kangal - Automatic loader
[](https://artifacthub.io/packages/search?repo=kangal)
[](https://codecov.io/gh/hellofresh/kangal)
Run performance tests in Kubernetes cluster with Kangal.
___
## Table of content
- [Why Kangal?](#why-kangal)
- [Key features](#key-features)
- [How it works](#how-it-works)
- [Supported backends](#supported-backends)
- [Architectural diagram](#architectural-diagram)
- [Components](#components)
- [LoadTest Custom Resource](#loadtest-custom-resource)
- [Kangal Proxy](#kangal-proxy)
- [Kangal Controller](#kangal-controller)
- [Quickstart guide](#quickstart-guide)
- [Installing using helm](#installing-using-helm)
- [Creating first LoadTest](#creating-first-loadtest)
- [Documentation](docs/index.md)
- [Contributing](#contributing)
- [Support](#support)
## Why Kangal?
In Kangal project, the name stands for "**K**ubernetes **an**d **G**o **A**utomatic **L**oader".
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](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/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](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**](https://jmeter.apache.org/)
- [**Locust**](https://locust.io/)
- [**ghz**](https://ghz.sh/)
- [**k6**](https://k6.io/)
Read more about each of them in [docs/index.md](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](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
### 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](https://swagger.io/specification/).
If you prefer to use Postman you can also import [openapi.json](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:
```shell
helm repo add kangal https://hellofresh.github.io/kangal
```
Now, install the chart using the following command:
```shell
helm install kangal kangal/kangal
```
That's it, Kangal should be installed, check if is all correct by running:
```shell
$ 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](charts/kangal/README.md).
### Creating first LoadTest
To run a LoadTest you first need to find Kangal proxy endpoint. Use this command:
```shell
$ 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](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). If it is not the case you can use [Port Forwarding](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/).
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.
```shell
$ 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
```
```json
{
"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:
```shell
curl http://${KANGAL_PROXY_ADDRESS}/load-test/loadtest-dunking-hedgehog
```
```json
{
"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:
```shell
$ kubectl get namespaces
NAME STATUS AGE
...
loadtest-dunking-hedgehog Active 3s
```
And you can check if the Pods started correctly using:
```shell
$ 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](docs/index.md).
## Contributing
Please check the [contribution guide](CONTRIBUTING.md) before opening a PR.
## Support
If you need support, start with the [troubleshooting guide](docs/troubleshooting.md), and work your way through the process that we've outlined.