Ansible Role locust

Manages Locust.io instances.

Requirements

Locust.io requires ZeroMQ. This role will therefor install the ZeroMQ library.

On Ubunto, libzmq-devel will be installed.

On CentOS, zeromq-devel and gcc will be installed to compile the necessary python pips for Locust.io. The upstream ZeroMQ yum repository will be registered and enabled to do this.

All python related software requirements will be auto-installed inside a virtualenv.

Role Parameters

Common parameters for all modes

Variable	Default	Comments (type)
instance_name	default	Name to distiguish instances.
mode	slave	Must be either master, slave or stand-alone
state	started	State of Locust.io on the host.
enabled	false	If true, start this instance after reboots
run_as_user	root	Which unix user to launch Locust.io as
run_as_group	root	Which unix group to launch Locust.io under
instance_data		Path to data to be copied into instance dir
locust_classes	[]	List of client classes to run
locustfile		The Locust.io scenario file to play
logfile		Filename of the Locust.io logfile
loglevel		Locust.io log level
base_dir	/opt/locust.io	Where to put Locust.io & instance data

Master Mode and Stand-Alone Mode Parameters

Variable	Default	Comments (type)
host		URL of the host to load test
web_host		IP address to bind the web interface to
web_port		Port to bind the web interface to
csv		Base name of CSV report files

Master Mode Parameters

Variable	Default	Comments (type)
bind_host		IP address to bind the master instance to
bind_port		TCP port number of the Locust.io master
no_web	true	No web interface, start tests immediately
expect_slaves		How many slaves to wait for before starting
clients		Number of clients. Required for no_web
hatch_rate		Spawn rate of clients. Required for no_web
num_request		Number of requests to perform; for no_web
run_time		How long to test, e.g. '1h30m'; for no_web

Slave Mode Parameters

Variable	Default	Comments (type)
master_host		IP, hostname or FQDN of the Locust.io master
master_port	5557	TCP port number of the Locust.io master

The state parameter can be one of:

• started - Locust.io should be up and running
• restarted - Locust.io should be freshly restarted
• stopped - Locust.io should be present but should not be running
• absent - Locust.io should not be installed

A directory named /opt/locust.io will be created. Inside of it, a subdirectory per instance will be created. If state is set to absent, this subdirectory will be removed. The location can be changed with the base_dir parameter, but if you do you will have to specify the base_dir parameter again on all future plays controlling this instance, as otherwise it will not be found. The base_dir itself will be removed along with the last instance.

The instance_data parameter can point to a file or directory to be copied into the instance subdirectory. For example, instance_data: data/ would copy the data/ directory inside your playbook's files/ directory to the instance subfolder.

You can specify the locustfile parameter as a path relative to the instance_data content root. (see example below)

Note: the run_time parameter requires Locust.io v0.9, which is not available via pip, as of this writing.

Note: for reasons unknown Locust.io requires specifying bind_host: '*' but web_host: '' to bind to all available interfaces, respectively.

Operating Systems

This role was developed and tested for CentOS 7.4. It was also tested for Ubuntu 16.04. (Xenial)

Dependencies

None

Example Playbook

To have a running Locust.io master/slave setup you could do this:

- hosts: locust_master
  tasks:
  - include_role:
       name: tinx.locust
    vars:
       mode: master
       instance_data: data/
       locustfile: 'stresstest-prod.py'

- hosts: locust_slaves
  tasks:
  - include_role:
       name: tinx.locust
    vars:
       mode: slave
       master_host: locust-master.example.com
       instance_data: data/
       locustfile: 'stresstest-prod.py'

The master would wait for at least one slave to connect and would then start testing.

Examples

There are further examples in the examples/ directory:

• running a master/slave setup inside two docker containers
• building docker images using ansible-container

Testing

Molecule tests are provided. Naturally, they require additional dependencies.

License

BSD

Author Information

• Andreas Jaekel