--- title: "AWS API gateway - CloudFormation" slug: "aws-api-gateway-cloudformation" description: "Learn how to deploy AWS API Gateway using CloudFormation with Traceable AI. This guide covers step-by-step instructions, configuration details, and CLI commands to monitor REST and HTTP API gateways. Follow best practices for a secure and automated deployment across multiple AWS regions and accounts." tags: ["Account", "AWS API Gateway", "aws"] updated: 2025-04-07T14:41:53Z published: 2025-04-07T14:41:53Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # 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: ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_aws_monitoring_traffic_flow.png) 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** (![image-1638268402925](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/image-1638268402925.png))**→Account** → **Agent Token**. - Download the `template.yaml` file from Traceable’s [download](https://downloads.traceable.ai/#install/aws-api-gateway/cloudformation/latest/aws-api-gateway/) 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/](https://aws.amazon.com/api-gateway/). 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**: JSONJSON ** ** ```json {  "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: ActionScriptActionScript ** ** ```actionscript aws configure ``` The following example shows sample values. Replace them with your values to configure the credentials correctly. ActionScriptActionScript ** ** ```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 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: ```actionscript 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config). ### 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**. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_aws_apigw_cf_ui_console_step_1.png) 2. Click on **Create Stack**. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_aws_apigw_cf_ui_console_step_2.png) 3. In the Prerequisite—Prepare template section, **Choose an existing template**;****in the****Specify template section**,**select **Upload a template file**. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_aws_apigw_cf_ui_console_step_3.png) 4. Specify a stack name and configure the various template file values. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_aws_apigw_cf_ui_console_step_4.png) 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](/v1/docs/aws-api-gateway-cloudformation#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. ```plaintext 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`: Parameters in this example: - Provides a list of parameters to override the default values defined in the CloudFormation template. Each parameter is specified as a `Key=Value` pair. - `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](/v1/docs/aws-api-gateway-cloudformation#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](/v1/docs/aws-api-gateway-cloudformation#accounts) JSON, the `CrossAccountRoleARNs` value would be: ```plaintext 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](/v1/docs/aws-api-gateway#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](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volume-types.html). | 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 ```json {  "api_list": ["625vetvy0f"],  "cross_account_role_arn": "",  "exclude": false,  "region": "us-east-1" } ``` For example, this will be represented as: ```plaintext Accounts=ewogICJhcGlfbGlzdCI6IFsKICAgICI2MjV2ZXR2eTBmIgogIF0sCiAgImNyb3NzX2FjY291bnRfcm9sZV9hcm4iOiAiIiwKICAiZXhjbHVkZSI6IGZhbHNlLAogICJyZWdpb24iOiAidXMtZWFzdC0xIgp9 ``` If there are two accounts, the JSON objects should be comma-separated: ```json {  "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: ```plaintext 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. ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_aws_apigw_delete_stack_UI.png) ### Uninstall using CLI Enter the following command to delete all Traceable instances created to capture traffic on the AWS API gateway. ```plaintext aws cloudformation delete-stack --stack-name ``` Amazon CloudWatch is a monitoring and observability service provided by Amazon Web Services (AWS). It is designed to collect and track metrics, collect and monitor log files, and set alarms for resource utilization, performance, and operational health of various AWS services and applications. 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. KMS Key (often referred to as a customer master key or CMK) is the primary resource in AWS KMS. It is used to encrypt and decrypt data and to create data encryption keys (DEKs) that you can use outside of AWS KMS. ## Related - [Deployment using Terraform](/aws-api-gateway-terraform.md) - [AWS traffic mirroring](/aws-traffic-mirroring.md) - [Install using CloudFormation](/install-tpa-using-cloudformation.md)