AWS VPC mirroring - Terraform template
  • 09 May 2023
  • 7 Minutes to read
  • PDF

AWS VPC mirroring - Terraform template

  • PDF

Article Summary

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:

  • 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 Administration (image-1638268402925)AccountAgent Token
    Information
    A tfvars file is a file that contains variable assignments for use with Terraform, a tool for building, changing, and versioning infrastructure safely and efficiently. The tfvars 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 .tfvars file extension, and the variable assignments are in a key-value format.
  • Make sure that Terraform is already installed. For more information on installing Terraform, see Download Terraform
  • 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.

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

    Note:
    Named AWS profiles are a feature of the AWS CLI that allow users to configure multiple sets of AWS access credentials and settings on a single machine. Each profile is identified by a unique name and can have its set of AWS access keys, default region, output format, and other settings.

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

    aws configure get region

    For more information on configuration, see AWS documentation.


Download

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

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

Untar the tarball. Enter the following command:

tar xvzf traffic-mirroring-aws.tar.gz

Installation

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

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

Type

Default value

Description

vpc_id

string

""

VPC where Traceable will be deployed.

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

tags

map(string)

{}

Additional tags to be applied on all the Traceable resources.

install_packagesbooltrueInstall Traceable and mirroring packages on the Traceable instances. This variable will be ignored if custom_ami_id is not provided.
custom_ami_idstring""Custom AMI ID to be used for Traceable instances.
mirroring_session_lambdaobject

 —

See the mirroring session lambda section.

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 theinstance_group_configuration.

mirror_source

The mirror_source object has the following values:

Name

Type

Default value

Description

type

string

"MANUAL"

Type of mirror source. Possible values are LOAD_BALANCER, TARGET_GROUP, ECS_CLUSTER, and MANUAL.

value

string

""

Depending on the type, the possible values could be: 

  • LOAD_BALANCER - Provide a comma-separated list of load balancers. 
  • TARGET_GROUP - Provide a comma-separated list of target groups. 
  • ECS_CLUSTER - Provide the name of an ECS cluster, for example, value = "MY_CLUSTER"
  • MANUAL - This must be empty, that is, value = ""

vpc_id

string

""

comma-separated list of VPC IDs where mirrored sources exist, for example,vpc_id = "MY_VPC"

instance_group_configuration

The instance_group_configuration has the following values:

Name

Type

Default value

Description

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. Instance family must be m4, m5, or c5 and instance size must be large, xlarge, 2xlarge, or 4xlarge.

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.

mirroring_session_lambda

The mirroring_session_lambda has the following values:

NameTypeDefault valueDescription
timeoutnumber600 secondsMirroring session lambda timeout in seconds.
intervalnumber15 minutesMirroring 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
falseIf you set this value to true, Traceable creates traffic mirroring sessions and filter rules for targets even if their health status is not healthy.

Apply terraform

Run the following commands to apply the terraform changes:

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 themirror_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.
  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 invpc_A while you wish to deploy Traceable invpc_B. If the subnets used to deploy Traceable aresubnet_1subnet_2, and so on, with CIDRs as cidr_1,cidr_2, and so on, then follow these two steps:

  • Establish a peering connectionpcx_AB betweenvpc_A andvpc_B.
  • Add new routes in the main route table ofvpc_A with target aspcx_AB and destination ascidr_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 VPCvpc_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:

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 (sayvpc_A2vpc_A3, and so on) then you need to repeat the above two steps for vpc_A2vpc_A3, and so on, and finally add these VPCs to thevpc_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:

terraform destroy



Was this article helpful?