{"id":19662071,"url":"https://github.com/ingojaeckel/armory","last_synced_at":"2026-05-15T10:04:20.373Z","repository":{"id":136468366,"uuid":"80372428","full_name":"ingojaeckel/armory","owner":"ingojaeckel","description":"A load testing-as-a-service framework written in Go","archived":false,"fork":false,"pushed_at":"2017-04-11T05:31:43.000Z","size":105,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-10T01:51:27.734Z","etag":null,"topics":["aws","ec2","gatling","golang","load-testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ingojaeckel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-29T21:02:29.000Z","updated_at":"2021-08-10T11:15:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"c40f4cf3-d3b8-40a4-b26d-fc81be46c95e","html_url":"https://github.com/ingojaeckel/armory","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingojaeckel%2Farmory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingojaeckel%2Farmory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingojaeckel%2Farmory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingojaeckel%2Farmory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ingojaeckel","download_url":"https://codeload.github.com/ingojaeckel/armory/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240970423,"owners_count":19886559,"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","ec2","gatling","golang","load-testing"],"created_at":"2024-11-11T16:09:29.224Z","updated_at":"2025-11-22T10:01:31.367Z","avatar_url":"https://github.com/ingojaeckel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://img.shields.io/travis/ingojaeckel/armory.svg)](https://travis-ci.org/ingojaeckel/armory)\n[![Code Coverage Status](https://img.shields.io/codecov/c/github/ingojaeckel/armory.svg)](https://codecov.io/gh/ingojaeckel/armory)\n\n# Armory - a load testing-as-a-service framework.\n\nArmory is a framework to simplify load testing micro-services. It removes the need to manage load test instances, copy scripts, upload results, etc. If you are load testing a lot of different services, Armory might help you to unify some of the different testing approaches applied by your team. Most importantly it helps you to get rid of those idle load generator instances.\n\n**Status**: Armory is not ready for prime time yet. It is still under active development. Proceed with caution. Do not use this in your production AWS account. Only provide very limited permissions to Armory.\n\n# Usage\n\nArmory attempts to integrate well with your existing CI/CD processes. Once deployed you can trigger and monitor load tests from your CI server. The typical use of Armory can be broken down into the following steps:\n\n![Architecture](doc/Architecture.png)\n\n1. A new test is triggered by the build server manually or scheduled (e.g. daily test).\n2. The build server pulls your load test scripts from a repository. Once all data is pulled the CI server will package those files to build a LT artifact file (see below for information about the format).\n3. The CI server uploads the LT artifact to S3.\n4. The CI server triggers the execution of a new test by sending an HTTP request to the Armory Frontend instance. This will return a test ID. The ID can be used to check the status of the test periodically.\n\n# Getting started\n\nTake a look at the [armory-getting-started](https://github.com/ingojaeckel/armory-getting-started) project to build \u0026 deploy your customized version of armory. Consider using this as a template for the build job which will deploy armory to your AWS account. Once you have deployed armory, use the following instructions to start new load tests using the armory frontend.\n\n## Run load tests via Armory\n\n* Create a new load test package. For more information on the expected LT package file format see below.\n* Start the test by invoking a `PUT /rest/test` request against the Armory frontend (request format below). This will return a unique load test identifier.\n* Check the LT status by invoking a `GET /rest/rest?id={test-id}`. Let your CI server poll for the test status.\n\n### Load test package format\n\nA valid load test package is a `.tar.bz2` file containing the following files \u0026 directories:\n\n* `/sim/*`: any simulation files or supporting source code; *required*\n* `/misc/*`: additional files that are necessary to run the load test e.g. input files that are consumed by the LT simulation; optional\n* `/lib/*.jar`: libraries that are required in order to run the simulation i.e. dependencies of the simulation which are not already part of Gatling; optional\n\nCheckout the `/doc/example-archive/` folder for an example load test archive.\n\n### Submit load tests to Armory\n\nTo start a new load test send the following request to the Armory frontend:\n\n* PUT /rest/test\n* Body:\n    * artifact-url: URL in S3 to the Load Test Archive file that should be run\n    * output: URL in S3 to where the aggregated results should be uploaded.\n    * instance-count: Number of EC2 instances (workers)\n    * instance-type: Type of EC2 instances\n    * simulation-class: Name of the simulation class\n* Response:\n    * Load test ID - can be used to check the status while the test is running\n* Example Body:\n\n```\nPUT\n{\n  \"artifact-url\":     \"https://s3-us-west-1.amazonaws.com/my-loadtest-result-bucket/example.tar.bz2\",\n  \"output\":           \"s3://output/\",\n  \"instance-count\":   1,\n  \"instance-type\":    \"t2.micro\",\n  \"region\":           \"us-east-1\",\n  \"simulation-class\": \"com.example.Loadtest\"\n}\n```\n\n* Example Response:\n\n```\n{\n  \"id\": \"123\"\n}\n```\n\n### Retrieve the status of a running load test\n\nSend the following request to the Armory frontend server:\n\n* GET /rest/test?id={test-id}\n* Response:\n\n```\n{ \"status\": \"starting|running|...\" }\n```\n\n* Example Response:\n\n```\n{\n  \"status\": \"running\"\n}\n```\n\n## Deploy Armory to EC2\n\n* `git clone git@github.com:ingojaeckel/armory.git`\n* Adjust the configuration in `src/my_configuration.go`. This includes your EC2 security group, VPC subnet, IAM information, etc. Insert a access/secret key pair which is authorized to start EC2 instances and upload results to the bucket you configured.\n    * There are existing Packer \u0026 Terraform scripts within the `/infra` folder that will help you to setup all infrastructure needed to run Armory (the VPC, subnet, IAM profiles, CodeDeploy, an EC2 instance acting as the frontend, etc).\n* Run the following to build the Armory executable:\n\n```\ncd src\n./scripts/build.sh\n```\n\n* Deploy the executable to an EC2 instance. A `t2.nano` instance will be sufficient. Consider reusing the `/scripts/{package_for,trigger}_codedeploy.sh` scripts and the configuration from `/infra/codedeploy` to deploy Armory.\n\n# Building blocks\n\nThe Armory framework consists of the following technical building blocks:\n\n* [Gatling](https://gatling.io/) as a load generator. Load test scripts are written in [Scala](https://www.scala-lang.org/).\n* A RESTful web app written in [Golang](https://golang.org) for the frontend and the load generator instances.\n* [packer](https://www.packer.io/) to create the AMIs we are running on EC2.\n* [terraform](https://www.terraform.io/) to manage the infrastructure required to run load tests.\n* [Docker](https://www.docker.com) for repeatable builds.\n* AWS [CodeDeploy](https://aws.amazon.com/codedeploy/) for deployments and AWS [EC2](https://aws.amazon.com/ec2/) \u0026 [S3](https://aws.amazon.com/s3/) to run the tests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingojaeckel%2Farmory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fingojaeckel%2Farmory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingojaeckel%2Farmory/lists"}