Reference
CLI
run-fargate

run-fargate - run an Artillery test on AWS Fargate

Added inv2.0.0-33 
artillery run-fargate [options] <script>

Options

The only required flag is --region which sets the region in which the test will run. The --count flag controls the horizontal scaling of the load test, i.e. setting --count 10 can be thought of as multiplying the load that will be generated by a factor of 10. All other flags are optional.

Fargate-specific flags

OptionDescription
--region <region>The AWS region to run in (us-east-1, us-west-1, eu-west-1, eu-central-1, ap-south-1, ap-northeast-1)
--count <num>Number of load generator containers to launch
--tags <tags>Comma-separated list of tags in key:value format to tag the test run, for example: --tags team:sre,service:foo
--note <text>Attach a note to a text, for example: --note "This is a spike test for service foo"
--cluster <name>Name of the Fargate cluster to run the test on. Artillery will create an empty cluster to run the test on by default if not specified.
--launch-config <json>Customize launch configuration of ECS/Fargate tasks
--launch-type <launch-type>The launch type to use for the test (ecs:fargate, ecs:ec2). Defaults to Fargate (ecs:fargate).
--max-duration <num>Maximum duration of the test run in seconds
--packages <path>Path to a package.json file to explicitly specify dependencies for the test script. If not set, Artillery will autodetect all dependencies.
--security-group-ids <ids>Comma-separated list of AWS VPC security group IDs to launch Fargate tasks in
--subnet-ids <ids>Comma-separated list of AWS VPC subnet IDs to launch Fargate tasks in
--task-role-name <role-name>IAM role name for Fargate containers to assume
--secret <secret-name1> <secret-name2>Makes secrets (list separated by spaces) available to workers as environment variables. The secret must exist in SSM parameter store for the given region, under /artilleryio/<secret-name>
--cpu
Added inv2.0.1		Set task vCPU units. Value may be set as a number of vCPUs between 1-16 (e.g. 4), or as number of vCPU units (e.g. 4096). Default: 4
--memory
Added inv2.0.1		Set task memory. Value may be set as number of GB between 1-120 (e.g. 8), or as MiB (e.g. 8192)
--spot
Added inv2.0.5		Use Fargate spot instances. Ignored when --launch-type is set to ecs:ec2

Configuring vCPU and memory with --cpu and --memory

Added inv2.0.1

You can configure the amount of CPU and memory available to each Artillery worker task running on Fargate with the --cpu and --memory flags. The default values are 4 vCPUs and 8 GB of memory.

When customizing the amount of CPU and memory a valid combination of values must be specified. You can learn more about valid combinations in the AWS documentation on https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-tasks-services.html#fargate-tasks-size (opens in a new tab).

Using --launch-config

You can customize the runtime environment of Artillery tasks running on ECS via the --launch-config flag. The following customizations are supported:

Examples

Increase the amount of memory available to 8 GB and use 4 vCPUs for each task:

artillery run-fargate \
  --region us-east-1 \
  --count 10
  --launch-config '{"cpu": 4096, "memory": 8192}' \
  my-script.yaml

CPU and memory on Fargate

When using Fargate, cpu and memory values cannot be increased independently of each other. You must specify supported values as defined in the AWS documentation (opens in a new tab).

Increase the number of file descriptors for each worker:

artillery run-test \
  --region us-east-1 \
  --count 10 \
  --launch-config '{"ulimits":[{"name":"nofile","softLimit":"16384","hardLimit":"16384"}]}' \
  my-script.yaml

The default limit of file descriptors set by Artillery is 8192 per worker. If your test runs open lots of TCP connections, your workers may run out of file descriptors, which surface as EMFILE errors. Increasing the number of file descriptors as shown above can help resolve the issue.

Run a test script setting two environment variables named VAR1 and VAR2 for Artillery workers running on ECS/Fargate.

Those environment variables will be available inside the Artillery test script via $env.VAR1 and $env.VAR2.

artillery run-test \
  --region us-east-1 \
  --count 10 \
  --launch-config '{"environment": [{"name":"VAR1", "value":"hello"},{"name":"VAR2","value":"world"}]}' \
  my-script.yaml

Using --spot

Added inv2.0.5

The --spot flag allows you to run using AWS Fargate spot (opens in a new tab), which has a much lower cost to run.

However, spot instances can randomly be terminated by AWS. This is ideal to use for running short tests (as it's unlikely the instance will be terminated), or for running tests that can tolerate interruptions.

⚠️

Using the --spot flag will require recreating existing clusters the first time you use it. Simply delete your existing Artillery Fargate cluster, and let the CLI automatically recreate it (with spot capabilities now enabled).

Shared flags

The run-fargate command shares many options with the run command:

OptionDescription
--output, -oWrite a JSON report to a file
--environment, -eRun the test using the specified environment
--config, -cLoad config section from another file
--scenario-name
Added inv2.0.0-38		Run only the specified scenario
--overridesOverride values in the test script dynamically
--target, -tSet or override target URL for the test
--variables, -vSet scenario variables dynamically
--dotenv <path>Set environment variables with a .env file
--quiet, -q
Added inv2.0.10		Run in quiet mode
--insecure, -kTurn off TLS verification. Should not be used in production
--record and --key
Added inv2.0.0-33		Record test run to Artillery Cloud (opens in a new tab). Learn more about recording test runs (opens in a new tab).
run-lambdaquick