{"id":13651572,"url":"https://github.com/smithmicro/jmeter-ecs","last_synced_at":"2025-04-22T22:31:31.316Z","repository":{"id":155604178,"uuid":"86936042","full_name":"smithmicro/jmeter-ecs","owner":"smithmicro","description":"JMeter Docker Image for Distributed Testing on EC2 Container Service (ECS)","archived":false,"fork":false,"pushed_at":"2022-11-22T10:18:35.000Z","size":71,"stargazers_count":42,"open_issues_count":16,"forks_count":34,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-01-25T06:39:25.674Z","etag":null,"topics":["aws","docker-image","ec2","ecs","jmeter"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smithmicro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-04-01T19:06:12.000Z","updated_at":"2023-11-14T13:31:34.000Z","dependencies_parsed_at":"2024-01-03T05:39:08.169Z","dependency_job_id":"cb207312-0e81-41cb-9ef9-968b53ae8ffc","html_url":"https://github.com/smithmicro/jmeter-ecs","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithmicro%2Fjmeter-ecs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithmicro%2Fjmeter-ecs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithmicro%2Fjmeter-ecs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithmicro%2Fjmeter-ecs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smithmicro","download_url":"https://codeload.github.com/smithmicro/jmeter-ecs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250333950,"owners_count":21413482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","docker-image","ec2","ecs","jmeter"],"created_at":"2024-08-02T02:00:50.608Z","updated_at":"2025-04-22T22:31:31.003Z","avatar_url":"https://github.com/smithmicro.png","language":"Shell","funding_links":[],"categories":["Distributed Testing"],"sub_categories":["Tutorials \u0026 Demo"],"readme":"# JMeter for ECS\nJMeter Images for Distributed Testing on EC2 Container Service (ECS)\n\nThis application uses two images:\n* `smithmicro/jmeter` - Contains the JMeter software that is deployed in ECS\n* `smithmicro/lucy` - The orchestration image that can run behind a corporate firewall and manages AWS resources\n\n_Warning: Using these Docker images will incur compute and storage costs in AWS.  Care is taken to terminate all instances and volumes after JMeter tests complete, but bugs could allow these resources to continue to run.  See the issues list for more detail._\n\n## How to Use\nThe `smithmicro/lucy` Docker image can be run as-is with a number of required environement variables.\n\nPrerequisites to use this image:\n* Create a VPC with at least one subnet as ECS requires the use of VPC **\n* Create a VPC security group that allows ports 22, 1099, 50000 and 51000 (tcp) and 4445 (udp) to the VPC **\n* Create a security key pair and place in the `keys` subdirectory\n* Have your AWS CLI Access Key ID/Secret Access Key handy\n* Replace or edit the included `plans/demo.jmx` to run your specific tests\n* Ensure you have a Role named `ecsInstanceRole`.  This is created by the ECS first-run experience.\n  * More details here: http://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html\n\n** If you do not have a VPC created, you can use the included `aws-setup.sh` script to create the VPC, Subnet and required Security Group.\n\nDocker run template:\n```\ndocker run -v \u003coath to jmx\u003e:/plans -v \u003cpath to pem\u003e:/keys -v \u003cpath to logs\u003e:/logs \\\n    --env AWS_ACCESS_KEY_ID=\u003ckey id\u003e \\\n    --env AWS_SECRET_ACCESS_KEY=\u003caccess key\u003e \\\n    --env AWS_DEFAULT_REGION=\u003cregion\u003e \\\n    --env SECURITY_GROUP=\u003csecurity group within your VPC\u003e \\\n    --env SUBNET_ID=\u003csubnet IDs within your VPC\u003e \\\n    --env KEY_NAME=\u003ckey pair name without extension\u003e \\\n    --env MINION_COUNT=\u003cnumber of minions\u003e \\\n    smithmicro/lucy /plans/demo.jmx\n```\nFor 5 test instances in N. Virginia, `docker run` would look like this, assuming your `jmeter-key.pem` file is located in the `keys` subdirectory:\n```\ndocker run -v $PWD/plans:/plans -v $PWD/keys:/keys -v $PWD/logs:/logs \\\n    --env AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPQRST \\\n    --env AWS_SECRET_ACCESS_KEY=abcdefghijklmnopqrstuvwxyz0123456789ABCDEF \\\n    --env AWS_DEFAULT_REGION=us-east-1 \\\n    --env SECURITY_GROUP=sg-12345678 \\\n    --env SUBNET_ID=subnet-12345678,subnet-87654321 \\\n    --env KEY_NAME=jmeter-key \\\n    --env MINION_COUNT=5 \\\n    smithmicro/lucy /plans/demo.jmx\n```\n\n## Architecture\nThis Docker image replaces the JMeter master/slave nomenclature with *Gru*, *Minion* and *Lucy*.  *Gru* manages the *Minions* from within ECS, but *Lucy* orchestrates the entire process.\n\n```\n+--------------------------------------+\n|  EC2                                 |\n|  +--------------------------------+  |\n|  |  ECS                           |  |\n|  |                +--------+      |  |\n|  |  +-------+     | +--------+    |  |      +--------+\n|  |  |       |----\u003e| | +--------+ ----------\u003e|        |\n|  |  |  Gru  |\u003c----| | |        | ----------\u003e| Target |\n|  |  |       |     +-| | Minion | ----------\u003e|        |\n|  |  +-------+       +-|        |  |  |      +--------+\n|  |     ^ |            +--------+  |  |\n|  +-----|-|------------------------+  |\n+--------|-|---------------------------+\n         | |\n    .jmx | | .log/.jtl\n         | v\n     +----------+\n     |          |\n     |   Lucy   |\n     |          |\n     +----------+\n```\n\n*Lucy* runs the `lucy.sh` script to perform the following steps:\n* Step 1 - Create the ECS Cluster\n* Step 2 - Wait for the cluster to have all container instances registered\n* Step 3 - Run a Minion Task with the requested instance count\n* Step 4 - Get Gru and Minion's instance ID's\n* Step 5 - Get IP addresses from Gru and Minions\n* Step 6 - Copy all files to Minions/Gru, or just the JMX\n* Step 7 - Run Gru with the specified JMX\n* Step 8 - Fetch the results from Gru\n* Step 9 - Delete the cluster\n\n### Volumes\nThe `lucy` container uses 3 volumes:\n* `/plans` - mapped into the orchestrator to provide the input JMX files\n* `/keys` - mapped into the orchestrator to provide the PEM file\n* `/logs` - mapped into the orchestrator to provide the output jmeter.log and results.jtl\n\n## Environment Variables\nThe following required and optional environment variables are supported:\n\n| Variable | Required | Default | Notes |\n|---|---|---|---|\n|AWS_DEFAULT_REGION|Yes|None|AWS Region (e.g. `us-east-1`)|\n|AWS_ACCESS_KEY_ID|Yes|None|AWS Access Key|\n|AWS_SECRET_ACCESS_KEY|Yes|None|AWS Secret Key|\n|INPUT_JMX|Yes|None|File path of JMeter Test file to run (.jmx).  You can optionally specify this as the first command line option of `docker run`|\n|KEY_NAME|Yes|None|AWS Security Key Pair .pem file (do not specify the .pem extension)|\n|SECURITY_GROUP|Yes|None|AWS Secuirty group that allows ports 22,1099,50000,51000/tcp and 4445/udp from all ports (e.g. sg-12345678)|\n|SUBNET_ID|Yes|None|One or more Subnets (comma separated) that are assigned to your VPC|\n|VPC_ID||VPC assigned to SUBNET_ID|We dautomatically erive this from your SUBNET_ID|\n|JMETER_VERSION||latest|smithmicro/jmeter Image tag.  See Docker Hub for [available versions](https://hub.docker.com/r/smithmicro/jmeter/tags/).|\n|INSTANCE_TYPE||t2.micro|To double your memory, pass `t2.small`|\n|MEM_LIMIT||950m|If you are using t2.small, set MEM_LIMIT to `1995m`|\n|MINION_COUNT||2||\n|PEM_PATH||/keys|This must match your Volume map.  See Volume section above.|\n|CLUSTER_NAME||JMeter|Name that appears in your AWS Cluster UI|\n|GRU_PRIVATE_IP||None|Set to `true` if you would like to run Lucy within AWS.  See GitHub [Issue 8](https://github.com/smithmicro/jmeter-ecs/issues/8) for details.|\n|JMETER_FLAGS||None|Custom JMeter command line options.  For example, passing `-X` will tell the Minion to exit at the end of the test|\n|RETAIN_CLUSTER||None|Set to `true` if you want to re-use your cluster for future tests.  Warning, you will incur AWS charges if you leave your cluster running.|\n|CUSTOM_PLUGIN_URL||None|The URL of a custom plugin you want to install in the Minions.  File will be copied to $JMETER_HOME/lib/ext.||\n|COPY_DIR||None|Set to `true` if you want to copy the directory in which the .jmx file is located to all Minions and Gru.  The files will be located in all Docker containers in ` /plans`.  Update your JMX file to reference external files at `/plans/...`|\n\n## Notes\nAll current JMeter Plugins are installed via the Plugins Manager.\n* https://jmeter-plugins.org/wiki/PluginsManager/\n\nFor more information on JMeter Distributed Testing, see:\n* http://jmeter.apache.org/usermanual/remote-test.html\n\n## Inspired by...\nhttps://en.wikipedia.org/wiki/Despicable_Me_2\n\n![Minions](https://pbs.twimg.com/tweet_video_thumb/C8CtmUbVwAAaboL.jpg \"Minions\")\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmithmicro%2Fjmeter-ecs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmithmicro%2Fjmeter-ecs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmithmicro%2Fjmeter-ecs/lists"}