# Reference > Cli > Run fargate

# `run-fargate` - run an Artillery test on AWS Fargate

```sh
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

| Option                                           | Description                                                                                                                                                                                   |
| :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--region <region>`                              | The AWS region to run in ([supported regions](/docs/load-testing-at-scale/aws-fargate#supported-regions)). |
| `--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 ECS 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 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>`                   | Task role for ECS/Fargate containers to assume ([`taskRoleArn`](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_role_arn) parameter)                                                                                                                                                |
| `--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`     | 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`  | Set task memory. Value may be set as number of GB between `1`-`120` (e.g. `8`), or as MiB (e.g. `8192`)                                                                                       |
| `--spot`    | Use [Fargate spot](#using---spot) instances. Ignored when `--launch-type` is set to `ecs:ec2`                                                                                                 |
| `--task-ephemeral-storage`    | Set [ephemeral storage](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-task-storage.html) for Artillery tasks. Maps to the `ephemeralStorage` task definition parameter. Value may be set as number of GB between `20`-`200`. Defailt: `20`. This option can only be set on Fargate.                     |
| `--container-dns-servers`    | Set custom DNS servers for the Artillery container. Value is a comma-separated list, e.g. `1.1.1.1,8.8.8.8`. Maps to the [`dnsServers`](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#:~:text=%3A%20%22string%22-,dnsServers,-Type%3A%20String%20array) container definition parameter. May be set only when `--launch-type` is set to `ecs:ec2`                                                                                                 |
| `--no-assign-public-ip`  | Disable automatic assignment of public IPs to worker tasks. This option is for use-cases where tasks need to run from a private subnet which has a NAT gateway attached to make sure that test traffic comes from known IP addresses. |

#### Configuring vCPU and memory with `--cpu` and `--memory`

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.

#### 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:

* `cpu` - The [number of CPU units reserved](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters#container_definition_environment) for each Artillery container. The default value is `1024`.
* `memory` - The [amount of memory](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters#container_definition_memory) presented to the Artillery container. The default value is `2048` on Fargate and `1024` on classic ECS.
* `environment` - The environment variables to set in the Artillery worker container.
* `ulimits` - Customize [ulimits](https://docs.aws.amazon.com/en_us/AmazonECS/latest/developerguide/task_definition_parameters#container_definition_limits) such as the number of available file descriptors (`nofile`).

##### Examples

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

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

> **Info:** **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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-cpu-memory-error).

Increase the number of file descriptors for each worker:

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

> **Info:** 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`.

```sh
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`

The `--spot` flag allows you to run using [AWS Fargate spot](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-capacity-providers.html), 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.

> **Warning:** 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).

#### Making additional files available in workers

Please use the [includeFiles](../test-script#includefiles---explicitly-bundling-files-with-the-test) option to make any additional files available to workers.

### Shared flags

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

| Option                                                          | Description                                                                                                                                                    |
| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--output`, `-o`                                                | Write a JSON report to a file                                                                                                                                  |
| `--environment`, `-e`                                           | Run the test using the specified environment                                                                                                                   |
| `--config`, `-c`                                                | Load `config` section from another file                                                                                                                        |
| `--scenario-name`                | Run only the specified scenario (exact match or regex)                                                                                                         |
| `--overrides`                                                   | Override values in the test script dynamically                                                                                                                 |
| `--target`, `-t`                                                | Set or override target URL for the test                                                                                                                        |
| `--variables`, `-v`                                             | Set scenario variables dynamically                                                                                                                             |
| `--env-file <path>` The `--dotenv` is deprecated since ()                                               | Set environment variables with a .env file                                                                                                                     |
| `--quiet`, `-q`           | Run in quiet mode                                                                                                                                              |
| `--insecure`, `-k`                                              | Turn off TLS verification. *Should not be used in production*                                                                                                  |
| `--name <value>`          | Set the name of the test run. This name will be shown in the Artillery Cloud dashboard and used to group multiple runs of the same test.                       |
| `--record` and `--key`  | Record test run to [Artillery Cloud](https://www.artillery.io/cloud). Learn more about [recording test runs](/docs/get-started/artillery-cloud). |