Deployment using CloudFormation

AWS CloudFormation is a service that provides a common language for describing and provisioning all the infrastructure resources in your cloud environment. CloudFormation allows you to use a simple text file to model and provision all the resources needed for their applications across all regions and accounts in an automated and secure manner. This file is known as a CloudFormation template, and it defines the resources and their properties.

Traceable fetches the cloudwatch logs every 5 minutes, parses the data, and sends it to the Traceable platform. The processed data is displayed in the Traceable UI. The following flow diagram shows how the traffic flows through:

The document details the steps for deploying the infrastructure via the AWS Management Console and AWS CLI, outlining the necessary parameters and configurations for a successful deployment.

---

Before you begin

Make a note of the following points before proceeding with configurations:

• Keep Traceable's access token handy. It will be used (optionally) when configuring the variables in the CloudFormation template. You can copy the access token by logging into your Traceable account and then navigating to Settings ()→Account → Agent Token.

• Download the template.yaml file from Traceable’s download site. Navigate to install → aws-api-gateway → cloudformation → latest.

REST API gateway

To monitor the REST API gateway, complete the following:

1. Navigate to the console. aws.amazon.com/apigateway/.

2. Select the API and then select the stage.

3. Navigate to Logs/tracing.

4. Select Full Request and Response Logs from Cloudwatch settings → Cloudwatch Logs drop-down list.

5. Mark Enable Access Logging as true under Custom Access Logging and append the following JSON in Log Format:

   {
     "requestId":"$context.requestId","ip":"$context.identity.sourceIp","httpMethod":"$context.httpMethod","path":"$context.path","status":"$context.status","responseLength":"$context.responseLength","domainName":"$context.domainName"}

HTTP API gateway

To monitor the HTTP API gateway, enable access logging and append the JSON mentioned above in the Log Format.

Configure AWS

Configure AWS in your shell and verify that the region is set correctly. Enter the following command to set up your AWS CLI installation:

aws configure

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

$ 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 myprofile has the credentials that you wish to use to deploy 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:

aws configure get region

Alternatively, you can configure the following environment variables:

• AWS_ACCESS_KEY_ID

• AWS_SECRET_ACCESS_KEY

• AWS_REGION or AWS_DEFAULT_REGION

• AWS_DEFAULT_OUTPUT

For more configuration information, see AWS documentation.

Multiple Accounts

A single AWS API Gateway account can support multiple accounts across different regions. However, each region within an account must be configured separately. This setup requires establishing cross-account IAM roles in each account, allowing the host account to authenticate and access the necessary resources.

---

Deploy CloudFormation through the AWS console

Log into your AWS account and complete the following steps:

1. Search for CloudFormation in your AWS console and click CloudFormation.

   
2. Click on Create Stack.

   
3. In the Prerequisite—Prepare template section, Choose an existing template; in the Specify template section**,** select Upload a template file.

   
4. Specify a stack name and configure the various template file values.

   
5. Add tags, select rollback options, and configure additional settings as needed.

6. Review the settings and create the stack. Monitor the progress and ensure the stack is created successfully.

---

Deploy using AWS CLI

Complete the following steps to deploy the CloudFormation template using AWS CLI:

1. Configure AWS as detailed in the Configure AWS section.

2. Update the parameters as required in the following command. The tags in the command are optional and are applied to all instances of the created stack where tags are supported.

   aws cloudformation deploy \
     --template-file deployments/aws-api-gateway/cloudformation/template.yaml \
     --stack-name traceable-apigw-dev \
     --capabilities CAPABILITY_NAMED_IAM \
     --parameter-overrides Accounts=W3siYXBpX2xpc3QiOlsiNjI1dmV \
     CrossAccountRoleARNs=arn:aws:iam::<***>:role/<***>,arn:aws:iam::<***>:role/<***> \
     TraceableAgentEndpoint=1.2.3.4 \
     TraceableServiceName=production \
     InstanceType=m4.xlarge \
     SubnetId=subnet-0fbc2fd16 \
     VpcId=vpc-02726c2b6ef \
     --tags key1=value1 key2=value2 key3=value3

Detailed Explanation

1. aws cloudformation deploy:

   • This command is used to deploy a CloudFormation stack using the AWS CLI.

2. --template-file deployments/aws-api-gateway/cloudformation/template.yaml:

   • Specifies the file path to the CloudFormation template. This template file contains the definitions of the AWS resources to be created or updated.

3. --stack-name traceable-apigw-dev:

   • Sets the name of the CloudFormation stack to traceable-apigw-dev. The stack name must be unique within an AWS region.

4. --capabilities CAPABILITY_NAMED_IAM:

   • Acknowledges that the stack might create IAM resources with custom names. This capability is required when the template includes creating or modifying IAM roles, policies, or users.

5. --parameter-overrides:

   • Provides a list of parameters to override the default values defined in the CloudFormation template. Each parameter is specified as a Key=Value pair.

   Parameters in this example:

   • Accounts=W3siYXBpX2xpc3QiOlsiNjI1dmV:

     • This appears to be a complex parameter, possibly JSON or an encoded string, specifying account-related configurations.

   • CrossAccountRoleARNs=arn:aws:iam::<***>:role/<***>,arn:aws:iam::<***>:role/<***>:

     • Specifies ARNs (Amazon Resource Names) of IAM roles that allow the stack to assume roles across different accounts.

   • TraceableAgentEndpoint=1.2.3.4:

     • Defines the endpoint for the Traceable Agent, where the agent will report data.

   • TraceableServiceName=production:

     • Sets the service name for Traceable traffic as "production."

   • InstanceType=m4.xlarge:

     • Specifies the EC2 instance type to be used; in this case, m4.xlarge.

   • SubnetId=subnet-0fbc2fd16:

     • The ID of the subnet where the EC2 instance will be deployed.

   • VpcId=vpc-02726c2b6ef:

     • The ID of the VPC (Virtual Private Cloud) where the subnet exists.

6. --tags key1=value1 key2=value2 key3=value3:

   • Adds tags to the stack resources. Tags are key-value pairs used to categorize and organize AWS resources.

   • Example tags:

     • key1=value1

     • key2=value2

     • key3=value3

Note

• Replace placeholders (<***>) with actual values.

• Ensure that the template file path (--template-file) is correct and accessible from where the command is executed.

• Validate that the IAM roles, VPC, and subnet exist and are correctly referenced in your AWS environment.

Parameters

The following tables explain the various parameters used in the CloudFormation template.

AWS API Gateway tracing agent configuration

Parameter	Optional/Mandatory	Description	Default value
Accounts	Mandatory	Refer to Accounts section.	-
CrossAccountRoleARNs	Mandatory	This parameter is a comma-separated list of ARNs. In the accounts JSON of the field cross_account_role_arn, take out the values of those fields, and form a comma-separated string. For the example in Accounts JSON, the CrossAccountRoleARNs value would be: arn:aws:iam::4324:role/customer-cross-account-role, arn:aws:iam::44324:role/test-cust-cross-account-role	-
LogGroupARNs	Mandatory	Enter a comma-separated list of ARNs of log groups for creating the IAM policy. For Example, arn:aws:logs:us-east-1:<***>:log-group:awsapigw-loggroup-1, arn:aws:logs:us-east-2:<***>:log-group:awsapigw-loggroup-2	-
tags	Optional	These will be the stack-wide tags.	-
ApiGatewayStagesARNs	Mandatory	Enter a comma-separated list of ARNs of stages of API Gateways for creating the IAM policy. For Example, arn:aws:apigateway:us-east-1::/restapis/api_id/stages/stage_name	-
TraceableAgentEndpoint	Optional	The Traceable Platform agent reporting endpoint for the agent. If not overridden, platform agent deployment will also be made on the same VM. For more information, see the following section.	http://localhost:5442
TraceableServiceName	Optional	The Traceable service name for the captured traffic.	aws-api-gateway
ServiceVersion	Optional	AWS API gateway agent version.	-
CronIntervalMins	Optional	Time interval (in minutes) at which the cron job is triggered.	5 minutes

Traceable Platform agent configuration

Configure these only when you wish to deploy the Traceable Platform Agent alongside the tracing agent instance. This configuration is applicable only when you have configured TraceableAgentEndpoint as http://localhost:5442.

Parameter	Optional/Mandatory	Description	Default value
TraceableRefreshToken	Mandatory	Traceable Platform token. This is the token you generated as part of a step in the Before you begin section.	-
TraceableEnvironment	Optional	Defines the environment, such as dev, QE, staging, etc.	aws-api-gateway
TraceableAPIEndpoint	Optional	Traceable Platform API endpoint.	api.traceable.ai
TPAVersion	Optional	Traceable Platform agent version.	-

Traceable EC2 instance configuration

The following table describes the Traceable EC2 instance configuration

Parameter	Optional/Mandatory	Description	Default value
InstanceType	Optional	The type of instance for deploying the agent.	m4.xlarge
SubnetID	Mandatory	The subnet ID of the subnet where the agent instance should be deployed.	-
VPCID	Mandatory	The VPC ID of the VPC in which the subnet given in SubnetID exists.	-
KeyName	Mandatory	The SSH keyname attached to the Traceable EC2 instance. (By default, port number 22 is not opened by EC2 instance).	-
AssignPublicIP	Optional	Set it to true if you wish to deploy the instance with a public IP address.	false

Traceable ECS deployment configuration

The following table lists the ECS-specific configuration:

Parameter	Description	Default	Mandatory
ClusterArn	ECS Fargate Cluster ARN for running the tasks in	NA	Yes, if using ECS
DeploymentMode	Configuration controlling whether to make EC2 based deployment or ECS based one. Allowed values are ecs and ec2	ec2	Set to ecs
EnableLogging	On ECS, the logs can saved to cloudwatch. Since we have extremely verbose logging, it’s disabled by default. Allowed values are true and false	false	No
AgentImage	AWS API Gateway Agent image to be deployed	traceableai/awsapigw:<TEMPLATE_VERSION>	Yes
AllowImagesFromECR	Configure IAM role to allow pulling images from ECR	true	No

Advanced configuration

Parameter	Optional/Mandatory	Description	Default value
RootDirectory	Optional	Root directory path for traceable files.	/var/traceable/aws-api-gateway
LogDirectory	Optional	Log directory path for traceable log files.	/var/traceable/log/aws-api-gateway
TraceableAgentMaxBatchSize	Optional	The maximum number of spans that you wish to bundle in a single request to the Traceable Platform agent.	500
ImageID	Mandatory	AMI ID that is used to launch an instance. Set this variable when you want to use AMI ID to launch an instance. This takes priority over ImageNameSSM parameter.	-
ImageNameSSM	Optional	Name of the Amazon Machine Image (AMI) to use (resolved from SSM). If the ImageID parameter is set, then that takes priority.	/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2
KmsKeyID	Optional	ARN of the custom KMS Key to use to encrypt the EBS volume.	alias/aws/ebs
EBSVolumeSize	Optional	Storage capacity (in GB) to allocate.	50 GB
EBSVolumeType	Optional	AWS EBS volume type. For more information, see Amazon EBS volume types.	gb2
EBSEncryption	Optional	Set it to true, if you wish to encrypt the volume.	true
BlockDeviceType	Optional	Device type for storage.	/dev/sdb

Accounts

The Accounts parameter takes a comma-separated list of base64-encoded values of the following JSON structure:

Field	Optional/Mandatory	Description
region	Mandatory	The AWS region from where you wish to capture the API traffic.
exclude	Mandatory	When set to true, the traffic is captured from all the API gateways except the ones provided in the api_list. When set to false, the traffic is captured only from the API listed in the api_list.
api_list	Mandatory	List of API IDs to consider for the above action. API_ID — If exclude = false, then monitor the API gateway that has ID = API_ID. However, if exclude = true, then do not monitor this API gateway. API_ID/STAGE_NAME — If exclude = false, then monitor the API gateway stage with name = STAGE_NAME and ID = API_ID. If exclude = true, then do not monitor this stage.
cross_account_role_arn	Mandatory	The ARN of the IAM role that authenticates this account for accessing the required resources from another account. Provide an empty string if the listed API gateways are in the same account.

Example

{
  "api_list": ["625vetvy0f"],
  "cross_account_role_arn": "",
  "exclude": false,
  "region": "us-east-1"
}

For example, this will be represented as:

Accounts=ewogICJhcGlfbGlzdCI6IFsKICAgICI2MjV2ZXR2eTBmIgogIF0sCiAgImNyb3NzX2FjY291bnRfcm9sZV9hcm4iOiAiIiwKICAiZXhjbHVkZSI6IGZhbHNlLAogICJyZWdpb24iOiAidXMtZWFzdC0xIgp9

If there are two accounts, the JSON objects should be comma-separated:

{
  "api_list": ["625vetvy0f"],
  "cross_account_role_arn": "",
  "exclude": false,
  "region": "us-east-1"
},
{
  "api_list": [],
  "cross_account_role_arn": "arn:aws:iam::account_2_id:role/traceable-cross-account-role",
  "exclude": true,
  "region": "us-east-1"
}

Encoded, this would be:

Accounts=ewogICJhcGlfbGlzdCI6IFsKICAgICI2MjV2ZXR2eTBmIgogIF0sCiAgImNyb3NzX2FjY291bnRfcm9sZV9hcm4iOiAiIiwKICAiZXhjbHVkZSI6IGZhbHNlLAogICJyZWdpb24iOiAidXMtZWFzdC0xIgp9,ewogICJhcGlfbGlzdCI6IFtdLAogICJjcm9zc19hY2NvdW50X3JvbGVfYXJuIjogImFybjphd3M6aWFtOjphY2NvdW50XzJfaWQ6cm9sZS90cmFjZWFibGUtY3Jvc3MtYWNjb3VudC1yb2xlIiwKICAiZXhjbHVkZSI6IHRydWUsCiAgInJlZ2lvbiI6ICJ1cy1lYXN0LTEiCn0=

---

Uninstall

You can uninstall the CloudFormation template through the AWS console or the CLI.

Uninstall through UI

Select the stack from the CloudFormation tab and click Delete to delete all the Traceable instances created to capture traffic on the AWS API gateway.

Uninstall using CLI

Enter the following command to delete all Traceable instances created to capture traffic on the AWS API gateway.

aws cloudformation delete-stack --stack-name <name of stack>