AWS Elastic Beanstalk Load Generator Example

This sample application uses the Locust open source load testing tool to create a simple load generator for your applications. The sample test definition locustfile.py tests the root of an endpoint passed in as an environment variable (TARGET_URL). For more information on the format of the test definition file, see Writing a locustfile.

Requirements:

AWS Elastic Beanstalk Command Line Interface (CLI)

Usage:

Automated Deployment

1. Edit/create the .env file and specify any/all configuration settings for your environment.

2. Create IAM Instance Profile

make profile-create

3. Deploy the Elastic Beanstalk service

make eb-deploy

4. If want to update the target url, update the LOCUST_TARGET_URL attribute in the .env file then run:

make eb-update

Note: git stage your changes before running the update so EB take on consideration your changes.

5. Terminate the application

make eb-terminate # terminate the eb application
make terminate-all # terminate the eb application and delete the IAM Instance Profile

Manual Deployment

You can get started using the following steps:

1. Install the AWS Elastic Beanstalk Command Line Interface (CLI).
2. Create an IAM Instance Profile named aws-elasticbeanstalk-locust-role with the policy in policy.json. For more information on how to create an IAM Instance Profile, see Create an IAM Instance Profile for Your Amazon EC2 Instances.
3. Run eb init -r <region> -p "Java 8" to initialize the folder for use with the CLI. Replace <region> with a region identifier such as us-west-2 (see Regions and Endpoints for a full list of region identifiers). For interactive mode, run eb init then,
   1. Pick a region of your choice.
   2. Select the [ Create New Application ] option.
   3. Enter the application name of your choice.
   4. Answer no to It appears you are using Python. Is this correct?.
   5. Select Java as the platform.
   6. Select Java 8 as the platform version.
   7. Choose whether you want SSH access to the Amazon EC2 instances.
      Note: If you choose to enable SSH and do not have an existing SSH key stored on AWS, the EB CLI requires ssh-keygen to be available on the path to generate SSH keys.
4. Run eb create -i c4.large --scale 1 --envvars TARGET_URL=<test URL> --instance_profile aws-elasticbeanstalk-locust-role to begin the creation of your load generation environment. Replace <test URL> with the URL of the web app that you want to test. Note: If you don't have a default VPC (most AWS accounts created in 2014 or later should have a default VPC in the account) in your account, please substitue the above instance type with c3.large.
   1. Enter the environment name of your choice.
   2. Enter the CNAME prefix you want to use for this environment.
5. Once the environment creation process completes, run eb open to open the Locust dashboard and start your tests.
6. To make changes to the test definition, edit the locustfile.py, save and commit the changes, and run eb deploy.
7. If you'd like to scale out the environment to more than 1 EC2 instance,
   1. Run eb scale <number of instances>. Replace <number of instances> with the number of EC2 instances you would like the environment to scale out to.
   2. If you are reducing the number of running instances in the above step, run eb deploy to reselect the master instance removal has been completed.
   3. Run eb open to open the Locust dashboard and start your tests.
8. When you are done with your tests, run eb terminate --all to clean up.

Note: Running Locust in distributed mode requires a master/slave architecture. This sample requires that the auto scaling minimum and maximum be set to the same value to ensure that the master isn't terminated by auto scaling. If for some reason the master instance is replaced, an eb deploy should be all it takes to fix it.

Useful AWS Elastic Beanstalk Command Line Interface:

eb open      # Open application dashboard
eb status    # Check application status
eb deploy    # Deploy application changes
eb list -v   # Show running applications list
eb logs      # Show application logs
eb printenv  # List application env variables
eb scale <number-of-instances-to-scale-to>      # Scale application
eb setenv TARGET_URL="https://new-url.test.com" # Update application TARGET_URL env variables