> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap/data-collection/mirroring/aws-mirroring/aws-mirroring-terraform.md).

# AWS mirroring - Terraform

The topic explains deploying Traceable’s platform agent using Terraform in AWS. The template also sets up traffic mirroring. Traffic mirroring can be used to capture a copy of the original data from the source network interface without disrupting your existing infrastructure and without adding any latency to your requests. For example, this mirrored data can be used for telemetry, attack detection, and so on.

***

## Before you begin

Make a note of the following before you proceed with the deployment:

* Make sure that you have Terraform 1.2 and later.
* Keep Traceable's access token handy. It will be used when you configure the variables in the `*.tfvars` file. You can copy the access token by logging into your Traceable platform and then navigate to **Settings** (![image-1638268402925](/files/pIisIRTSYeLJw44cMIFI)) → **Account** → **Agent Token**.

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>A <code>tfvars</code> file is a file that contains variable assignments for use with Terraform, a tool for building, changing, and versioning infrastructure safely and efficiently. The <code>tfvars</code> file allows users to set values for variables that are used in Terraform configuration files, and can be used to customize the infrastructure that is created or managed by Terraform. The file typically has a <code>.tfvars</code> file extension, and the variable assignments are in a key-value format.</p></div>
* Make sure that Terraform is already installed. For more information on installing Terraform, see [Download Terraform](https://www.terraform.io/downloads.html).
* Configure AWS in the shell you are using. Enter the following command to set up your AWS CLI installation:

  ```actionscript
  aws configure
  ```

  The following example shows sample values. Replace them with your values to configure the credentials correctly.

  ```actionscript
  $ aws configure
  AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
  AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  Default region name [None]: us-west-2
  Default output format [None]: json
  ```

  For more information on the `credentials` file, see [Configuration and credential file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).

  If you have configured named AWS profiles, export the environment variable `AWS_PROFILE=myprofile` where the profile named `myprofile`has the credentials which you wish to use in deploying the Traceable mirroring resources.

  Finally, run the following command and verify that the AWS region is set to the region where you wish to install Traceable:

  ```actionscript
  aws configure get region
  ```

  For more information on configuration, see [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config).

***

## Download

Enter the following command to download the AWS traffic mirroring tarball:

```language-actionscript
curl -O https://downloads.traceable.ai/install/traffic-mirroring/aws/terraform/latest/traffic-mirroring-aws.tar.gz
```

Untar the tarball. Enter the following command:

```language-actionscript
tar xvzf traffic-mirroring-aws.tar.gz
```

## Installation

To install, create a file `terraform.tfvars` with terraform variables as shown below.

```language-actionscript
vpc_id                  = "vpc-08dc789"
subnet_ids              = "subnet-123jndw,subnet-89sd3j"
assign_public_ip        = true
traceable_refresh_token = "my-token"
traceable_environment   = "my-env"
mirror_source = {
  type   = "ECS_CLUSTER"
  value  = "terraform-test"
  vpc_id = "vpc-08dc789"
}
instance_group_configuration = {
  key_name                           = "my-keypair-name"
  instance_type                      = "m4.large"
  traceable_refresh_token_secret_arn = ""
}
tags = {
  "TAG1"        = "VALUE1"
  "TAG2:GLOBAL" = "VALUE2"
  "TAG3"        = "VALUE3"
}
```

### Configure terraform variables

The following tables describe the various terraform variables.

| **Name**                        | <p><br></p><p><strong>Type</strong></p> | **Default value**             | **Description**                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------- | --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vpc_id`                        | `string`                                | `""`                          | VPC where you wish to deploy Traceable.                                                                                                                                                                                                                                                                                                                                                     |
| `subnet_ids`                    | `string`                                | `""`                          | Provide a comma-separated list of subnets where Traceable will be deployed. Provide one subnet for each availability zone across which the mirror sources exist.                                                                                                                                                                                                                            |
| `assign_public_ip`              | `bool`                                  | `false`                       | Assign public IP to Traceable instance/ECS service.                                                                                                                                                                                                                                                                                                                                         |
| `traceable_refresh_token`       | `string`                                | `""`                          | Traceable Platform token.                                                                                                                                                                                                                                                                                                                                                                   |
| `traceable_environment`         | `string`                                | `"traffic-mirroring"`         | Environment under which mirrored traffic will be seen on Traceable platform.                                                                                                                                                                                                                                                                                                                |
| `traceable_service_name`        | `string`                                | `"traffic-mirroring-service"` | Service name for the mirrored traffic.                                                                                                                                                                                                                                                                                                                                                      |
| `traceable_api_endpoint`        | `string`                                | `"api.traceable.ai"`          | Traceable API Endpoint.                                                                                                                                                                                                                                                                                                                                                                     |
| `deploy_traceable_agent_in_ecs` | `bool`                                  | `false`                       | Deploy Traceable in an ECS cluster.                                                                                                                                                                                                                                                                                                                                                         |
| `mirror_source`                 | `object`                                | —                             | See the next section.                                                                                                                                                                                                                                                                                                                                                                       |
| `instance_group_configuration`  | `object`                                | —                             | See the next section.                                                                                                                                                                                                                                                                                                                                                                       |
| `autoscaling_configuration`     | `object`                                | —                             | See the autoscaling configuration section.                                                                                                                                                                                                                                                                                                                                                  |
| `tags`                          | `map(string)`                           | `{}`                          | Additional tags to be applied on all the Traceable resources.                                                                                                                                                                                                                                                                                                                               |
| `install_packages`              | `bool`                                  | `true`                        | Install Traceable and mirroring packages on the Traceable instances. This variable will be ignored if `custom_ami_id` is not provided.                                                                                                                                                                                                                                                      |
| `custom_ami_id`                 | `string`                                | `""`                          | <p>Custom AMI ID to be used for Traceable instances.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Traceable only supports Ubuntu, CentOS 7, and Amazon Linux 2 AMIs in the <code>custom\_ami\_id</code> field. If you are using an ARM64-based AMI, then make sure that the chosen instance type is also based on ARM64 architecture.</p></div> |
| `mirroring_session_lambda`      | `object`                                | —                             | See the mirroring session lambda section.                                                                                                                                                                                                                                                                                                                                                   |
| `route53_configuration`         | `object`                                | —                             | See the [route53\_configuration](#route53configuration) section for more details.                                                                                                                                                                                                                                                                                                           |

You can deploy the Traceable agent either in an instance-group or in an ECS cluster. If `deploy_traceable_agent_in_ecs=true` then Traceable is deployed in an ECS cluster. In such a case, `instance_group_configuration` is ignored. If `deploy_traceable_agent_in_ecs=false` then Traceable is deployed in an Instance group. Refer below for the attributes which should be passed as part of the

instance\_group\_configuration.

#### mirror\_source

The mirror\_source object has the following values:

| **Name** | <p><br></p><p><strong>Type</strong></p> | <p><br></p><p><strong>Default value</strong></p> | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------- | --------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`   | `string`                                | `"MANUAL"`                                       | Type of mirror source. Possible values are `LOAD_BALANCER`, `LOAD_BALANCER_TAGS`, `TARGET_GROUP`, `ECS_CLUSTER`, `MANUAL`, and `FARGATE`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `value`  | `string`                                | `""`                                             | <p>Depending on the <code>type</code>, the possible values could be:</p><ul><li><code>LOAD\_BALANCER</code> - Provide a comma-separated list of load balancers.</li><li><code>LOAD\_BALANCER\_TAGS</code> - Provide a comma-separated list of load balancer tags. See the LOAD\_BALANCER\_TAGS section for more information.</li><li><code>TARGET\_GROUP</code> - Provide a comma-separated list of target groups.</li><li><code>ECS\_CLUSTER</code> - Provide the name of an ECS cluster, for example, <code>value = "MY\_CLUSTER"</code></li><li><code>MANUAL</code> and <code>FARGATE</code> - This must be empty, that is, <code>value = ""</code></li></ul> |
| `vpc_id` | `string`                                | `""`                                             | comma-separated list of VPC IDs where mirrored sources exist, for example, vpc\_id = "MY\_VPC"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

#### LOAD\_BALANCER\_TAGS

You can use `mirror_source` type if you wish to choose load balancers based on tags. All load balancers that match at least one of the tags provided in the `mirror_source` value are mirrored. The Tag can be either in the form of `key=value` or `key`.

**Example:** For the following input:

```actionscript
mirror_source = {
  type   = "LOAD_BALANCER_TAGS"
  value  = "app=development, traceable-mirror=true, traceable-app"
  vpc_id = "MY_VPC_ID"
}
```

All load balancers in the VPC `MY_VPC_ID` satisfying at least one of the following conditions will be mirrored:

* The load balancer has a tag with key `app` and value `development`.
* The load balancer has a tag with key `traceable-mirror` and value `true`.
* The load balancer has a tag with a key `traceable-app` and any value.

#### instance\_group\_configuration

The instance\_group\_configuration has the following values:

| <p><br></p><p><strong>Name</strong></p> | <p><br></p><p><strong>Type</strong></p><p><br></p> | <p><br></p><p><strong>Default value</strong></p><p><br></p> | <p><strong>Description</strong></p><p><br></p>                                                                                                                |
| --------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key_name`                              | `string`                                           | `""`                                                        | SSH key name that should be attached to Traceable EC2 instances.                                                                                              |
| `instance_type`                         | `string`                                           | `"m4.xlarge"`                                               | Instance type name of Traceable instances. Make sure that the VM instance where Traceable Platform agent will be installed has at least 4 vCPUs and 8 GB RAM. |
| `traceable_refresh_token_secret_arn`    | `string`                                           | `""`                                                        | ARN of secret where Traceable Platform token is stored. If you provide this, then `traceable_refresh_token` will be ignored.                                  |

#### autoscaling\_configuration

The autoscaling\_configuration has the following values:

| Name           | Type   | Default value | Description                                                                                                                                       |
| -------------- | ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_size`     | number | 20            | Maximum number of EC2 instances in the Traceable autoscaling group or ECS tasks in the Traceable ECS cluster.                                     |
| `target_value` | number | 80            | Target threshold value in percentage for average CPU and memory utilization in the autoscaling policy of Traceable Instance group or ECS service. |

#### mirroring\_session\_lambda

The mirroring\_session\_lambda has the following values:

| Name                       | Type     | Default value | Description                                                                                                                                                            |
| -------------------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timeout`                  | `number` | 600 seconds   | Mirroring session lambda timeout in seconds.                                                                                                                           |
| `interval`                 | `number` | 15 minutes    | Mirroring session lambda interval in minutes. Lambda runs at the configured interval to update mirror sessions and filter rules for any changes in the mirror sources. |
| `mirror_unhealthy_targets` | `bool`   | `false`       | If you set this value to true, Traceable creates traffic mirroring sessions and filter rules for targets even if their health status is not `healthy`.                 |

#### route53\_configuration

This variable is used only when you set `mirror_source.type = FARGATE`. The route53\_configuration object has the following values:

| Name                      | Type     | Default value          | Description                                                                                                                                                                                                                  |
| ------------------------- | -------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                    | `string` | `private.traceable.ai` | Defines the zone name for Traceable route53 private zone.                                                                                                                                                                    |
| `id`                      | `string` | `""`                   | Zone ID for existing route53 private zone. If this configuration is empty, a new private hosted zone is created for the Traceable NLB. Otherwise, Traceable uses the zone represented by this zone ID for the Traceable NLB. |
| `subdomain`               | `string` | `mirroring-fargate`    | Subdomain for route53 alias record created for the Traceable NLB.                                                                                                                                                            |
| `associate_traceable_vpc` | `bool`   | `true`                 | Defines whether Traceable VPC should be associated with the Traceable route53 zone.                                                                                                                                          |

### Apply terraform

Run the following commands to apply the terraform changes:

```language-actionscript
terraform init
terraform apply
```

***

## Mirroring in peered VPC

### what is peered VPC?

A peered VPC (Virtual Private Cloud) is a networking configuration in which two or more VPCs are connected to each other through a VPC peering connection. This allows resources in one VPC to communicate with resources in the other VPC as if they were on the same network. When VPCs are peered, their CIDR blocks become part of the same IP address range, which allows resources to communicate with each other using private IP addresses. This eliminates the need to use public IP addresses or a VPN connection to connect the VPCs.

AWS provides the capability to create VPC peering connections between VPCs in the same region, or across different regions, or across different accounts, using the VPC peering connection feature in the AWS Management Console.

### Traceable traffic-mirroring in peered VPC

If you want to deploy Traceable in a VPC which is different from the VPC where your mirror source(s) reside, it can be done as follows:

1. Under the mirror\_source configuration, provide the source VPC where the mirror sources reside.
2. Under the `vpc_id` configuration, provide the destination VPC where you wish to deploy Traceable.
3. Make sure that an active peering connection exists between the source and destination VPC provided above. For more information, see [VPC Peering](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html).
4. In the main route table of source VPC, add a new route with target as the peering connection and destination as the VPC CIDR of the destination VPC. This allows the mirrored traffic to go from the source VPC to destination VPC.

#### Example

Let us assume that the mirror sources are in

vpc\_A while you wish to deploy Traceable in

vpc\_B. If the subnets used to deploy Traceable are

subnet\_1

,

subnet\_2, and so on, with CIDRs as

cidr\_1,

cidr\_2, and so on, then follow these two steps:

* Establish a peering connection pcx\_AB between vpc\_A and vpc\_B.
* Add new routes in the main route table of vpc\_A with target as pcx\_AB and destination as cidr\_1, cidr\_2 , and so on. By doing this, we are trying to make sure that all the subnets where Traceable is deployed receive mirrored traffic from the source VPC vpc\_A.

Once done, you can use the following configuration to deploy Traceable. Rest of the configuration options can be used as described in [Configure terraform variables](#configure-terraform-variables):

```language-actionscript
vpc_id     = "<vpc_B>"
subnet_ids = "<subnet_1>,<subnet_2>,..."
mirror_source = {
  type   = "LOAD_BALANCER"
  value  = "terraform-test"
  vpc_id = "<vpc_A>"
}
```

Note that if the mirror sources are across more than one VPC (say

vpc\_A2

, vpc\_A3, and so on) then you need to repeat the above two steps for vpc\_A2

, vpc\_A3, and so on, and finally add these VPCs to the

vpc\_id

variable in

mirror\_source in the above configuration.

***

## Verification

Log into Traceable Platform to and navigate to **API Catalog > Services** to view the service name that you configured earlier.

***

## Uninstall

Run the following command from the same directory to destroy all the resources created in the installation step:

```language-actionscript
terraform destroy
```