Docker-Locust

The purpose of this project is to provide a ready and easy-to-use version of locust.io which also contains additional/useful features that are required.

Architecture

Docker-Locust container can be started in 4 different roles:

• master: Runs Locust's web interface where you start and stop the load test and see live statistics.
• slave: Simulates users and attacks the target url based on user parameters.
• controller: Orchestrates Master in automatic mode and downloads reports when the test is over.
• standalone: Automatically starts the above components locally.

There are 2 supported run types:

• Manual: when a user manually starts and stops a test via a Locust Master UI.
• Automatic: when a test is started by the Controller and runs for a specified time interval.

And there are 2 ways to deploy it:

• Local deployment (using standalone mode or docker-compose): when a singe machine can generate enough traffic.
• Distributed deployment: when multiple machines are required to generate a bigger load. This type of deployment might be used in AWS or Kubernetes. An example deployment with different container roles can be found in docker-compose. Using Automatic mode together with Distributed deployment requires the TOTAL_SLAVES variable to be set on the controller side.

Key advantages

1. It allows locust to read load test scenario/script from different resources (any HTTP/HTTPS URL, S3 bucket, and local machine).
2. It has the ability to be run in any CI tool e.g. Jenkins (It can start/stop load test automatically) and provides an HTML report at the end of a load test.
3. It is also possible to be deployed in AWS to create bigger load.

Requirements

1. docker engine version 1.9.1+
2. docker-compose version 1.6.0+ (optional)

Getting Started

Single machine / Standalone mode

docker-locust will be run as standalone version by default. Standalone version is for users who has only 1 single machine.

bash <(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy

You will be prompted for certains inputs required (You can use our example in github as load test script).

Target url: https://targeturl.com
Where load test script is stored: https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py
Number of slave(s): 4
Run type [automatic/manual]: manual

All of it can be simplify in one line:

bash <(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy --target=https://targeturl.com --locust-file=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py --slaves=4 --mode=manual

It is also possible to run with normal docker command:

docker run -i --rm -v $PWD/reports:/opt/reports -v ~/.aws:/root/.aws -v $PWD/:/opt/script -v $PWD/credentials:/meta/credentials -p 8089:8089 -e ROLE=standalone -e TARGET_HOST=https://targeturl.com -e LOCUST_FILE=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py -e SLAVE_MUL=4 -e AUTOMATIC=False registry.opensource.zalan.do/tip/docker-locust

Multiple machines

docker-locust can be run in multiple docker-containers. It is useful for users who has more than one machine to create bigger load. In this point we are using docker-compose, but it is also possible to run it in different ways, e.g. Cloudformation in AWS.

Run the application with the command:

DOCKER_COMPOSE=true bash <(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy

Read multiple files

docker-locust has the ability to read multiple files from s3 or any http/https, e.g. 1 file is the load test file / python file and 1 other file is json file where payloads are stored. Sample command:

bash <(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy --target=https://targeturl.com --locust-file=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple_post.py,https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/payloads.json --slaves=4 --mode=manual

Report Generation

Please add following lines to your load test script, like this example.

from locust.web import app
from src import report
app.add_url_rule('/htmlreport', 'htmlreport', report.download_report)

Simply after load test run, append "/htmlreport" to the URL which will download the report of the recent run. Example:

Setup in jenkins

docker-locust can be run automatically by using CI tool like jenkins.

Sample case:

• Number of users [total users that will be simulated]: 100
• Hatch rate [number of user will be added per second]: 5
• Duration [in seconds]: 30
• Target url: https://targeturl.com
• Load test script: simple.py
• Number of slaves: 4

Steps:

1. Put following command in "Execute shell" field:

   curl -O https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh && DOCKER_COMPOSE=true bash local.sh deploy --target=https://targeturl.com --locust-file=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py --slaves=4 --mode=automatic --users=100 --hatch-rate=5 --duration=30
   

2. Install html-publisher-plugin in jenkins to display load test result. Example configuration in jenkins job:

Troubleshooting

All output from containers can be see by running:

docker-compose logs -f

About the project versioning

A version number is combination between the locust version being supported and patch level, e.g. when a release is 0.7.3-p0, it support locust 0.7.3.

Capacity of docker-locust in AWS

All the data based on load testing against simple hello-world application with the default max_wait and min_wait values (1000ms).

NOTE:

1. Please check AWS-EC2-Type and AWS-EC2-pricing before use data above, because some of them could be changed time to time.
2. Number of total RPS could be different because of n reasons.

Contributions

Any feedback or contributions are welcome! Please check our guidelines.

Unit tests

Run the unit tests with this command:

local.sh test

License

See License

Security

See Security