--- title: "Install TPA using CloudFormation" slug: "install-tpa-using-cloudformation" updated: 2024-08-27T09:35:28Z published: 2024-08-27T09:35:28Z --- > ## 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. # Install using CloudFormation This document provides a comprehensive guide to installing the Traceable Platform agent using an ECS CloudFormation template. This guide includes installation steps via the AWS Management Console (UI) and the AWS Command Line Interface (CLI). --- ## Before you begin ### General prerequisites - **AWS Account:** Ensure you have an active AWS account. - **IAM Permissions:** Ensure you have the necessary IAM permissions to create and manage CloudFormation stacks, ECS services, load balancers, and Route53 records. The required permissions include: - `cloudformation:CreateStack` - `cloudformation:UpdateStack` - `cloudformation:DeleteStack` - `ecs:*` - `ec2:*` - `elasticloadbalancing:*` - `route53:*` - `iam:PassRole` (for any roles used in the CloudFormation template) - **VPC and Subnets:** Ensure you have an existing VPC and subnets configured in your AWS account that you can use to deploy the ECS service. - **Route53:** If your template includes Route53 configurations, ensure you have a hosted zone in Route53 and the necessary permissions to create and manage DNS records within that hosted zone. - **CloudFormation Template:** Ensure you have access to the ECS CloudFormation template file (`traceable-agent.yaml`). Download the template file from Traceable’s [download](https://downloads.traceable.ai/#install/traceable-agent/cf-templates/ecs/latest/) site. ### Additional prerequisites for AWS CLI - **AWS CLI Installed and Configured:** Install the AWS CLI on your local machine if it’s not already installed and configure it with your AWS credentials: ```plaintext aws configure ``` This will prompt you to enter your AWS Access Key ID, Secret Access Key, Default region name, and Default output format. - **Parameter File:** Prepare a JSON file (for example, `parameters.json`) that contains the parameters required by the template. ### Additional notes Make a note of the following based on the type of Traceable tracing agent that is deployed. #### **Application Load Balancer** When deploying the ECS service, it’s essential to understand how the Application Load Balancer (ALB) interacts with your setup. If the `LoadBalancerScheme` parameter is not explicitly disabled in the template, each port defined in your service will be fronted by an ALB. This means that traffic directed at your service will be managed and routed by the ALB according to the specified configurations. The following considerations apply when configuring TLS listeners and DNS routing through Route53: - For any TLS listener, if `DeployRoute53Record` is set to `true`, `HostedZoneId` and `DNSRecordName` are mandatory as a Route53Record is set up so that requests coming to this DNS record will be routed to the load balancer. - For gRPC target groups on ports 5442 or 5443, only TLS listeners are allowed. In this case, `ListenerCertificateArn` is mandatory. - By default, the HTTP target group on port 5442 will be deployed with a non-TLS listener. If a certificate (`ListenerCertificateArn`) is provided, then these will be deployed on TLS listeners using that certificate. - For port 5443, this is the TLS listener on the Traceable Platform Agent, so a TLS listener is deployed on port 5443, and traffic from the load balancer to the ECS service is re-encrypted. In this case, `ListenerCertificateArn`, `TLSPrivateKeyArn`, and `TLSCertificateArn` are mandatory fields. The `TLSPrivateKeyArn` and `TLSCertificateArn` correspond to AWS Secret ARNs, which are used to inject the certificate contents directly into the Traceable Agent cotainer. #### Agents configuration - **Non-TLS Traffic:** Routed to port 5442 and then to the reverse proxy on the Traceable Platform Agent (TPA). - **TLS Termination at Load Balancer (Port 5442):** Routed to the reverse proxy on TPA (only `ListenerCertificateArn` is required). For more information, see the table below. - **TLS Termination at Load Balancer (Port 5443) and Re-encryption:** Routed to port 5443 on TPA (`ListenerCertificateArn`, `TLSPrivateKeyArn`, and `TLSCertificateArn` are required). For more information, see the table below. #### OTLP-based agent configuration These configurations apply to the following OTLP-based tracing agents: - [eBPF](/docs/ebpf) - [Java](/docs/java) - [Go](/docs/go) - [.NET](/docs/azurefunctions) - [Python](/docs/python) - [Node.js](/docs/nodejs) **Configurations** - **TLS Termination at Load Balancer (Port 5442):** Routed to the port 5442 on TPA (only `ListenerCertificateArn` is required). - **TLS Termination at Load Balancer (Port 5443) and Re-encryption:** Routed to port 5443 on TPA (`ListenerCertificateArn`, `TLSPrivateKeyArn`, and `TLSCertificateArn` are required). #### Route53 configuration If the load balancer uses an HTTPS listener for the respective port, the SubjectAltName from the load balancer certificate should match the endpoint provided to the tracing agent. The template can deploy a Route53 record if no DNS record is configured. - **DeployRoute53Record:** Set to `true`. - **HostedZoneId:** The ID of the hosted zone where the Route53 record should be deployed. - **DNSRecordName:** The DNS record name should be in the format `<someprefix>.<hosted-zone-name>` --- ## Option 1 - Install Through AWS Management Console (UI) Complete the following steps to install the Traceable Platform agent using the AWS Management Console: 1. Open your web browser and log in to the AWS Management Console. 2. In the AWS Management Console, navigate to the CloudFormation service. 3. Click on **Create stack** and then choose **With new resources (standard)**. 4. **Specify the template**: 1. Select "Upload a template file" and then click on "Choose file" to upload your ECS CloudFormation template file (`traceable-agent.yaml`). 2. Click **Next**. 5. Enter a stack name (for example, `TraceableECSStack`). 6. Fill in the necessary parameters as per your environment and requirements. Refer to the table below for guidance on mandatory fields and those required for the load balancer. | Parameter | Description | Default value | Mandatory | | --- | --- | --- | --- | | `CPU` | vCPU for Traceable Agent | 2 | Yes | | `Memory` | Allowed Memory for the deployment | 8 GB | Yes | | `TraceableRefreshToken` | Refresh Token to connect to the `Traceable.ai` platform. | - | Yes | | `TraceableRefreshTokenArn` | AWS Secret Manager ARN for Traceable Platform refresh token. This parameter enhances the security and management of sensitive credentials (like refresh tokens) used by the Traceable Platform agent within your ECS environment. | - | No | | `TraceableEnvironment` | Environment name for Traceable | `api.traceable.ai:443` | Yes | | `TraceableRemoteEndpoint` | Remote endpoint for Traceable Platform | | | | `VpcId` | Existing VPC for Traceable agent | | Yes | | `LBSubnetIds` | Subnet IDs for deploying the load LoadBalancer | | No | | `AgentRestrictedSrcIPRange` | The IP address range(CIDR format) that can access Traceable Agent. Use VPC CIDR to restrict access from VPC | | Yes | | `ECSClusterName` | Name of existing ECS cluster | | Yes | | `TaskExecutionRoleARN` | The task execution role `arn` required for pulling the images, publishing the log to Cloud Watch, and accessing secrets from AWS Secret Manager. | | Yes | | `ServiceDiscoveryNameSpace` | Namespace for service discovery | `traceableai` | No | | `ECSLaunchType` | Launch type for agent | EC2 | Yes | | `AgentImage` | Docker image URL | The corresponding TPA image version as the script | Yes | | `PublicIP` | Assign public IP (For ECSLaunchType FARGATE) | `DISABLED` | Yes | | `LoadBalancerScheme` | Scheme of loadbalancer to be deployed in front of the ECS Service. Select disabled for not deploying a load balancer infront of the ECS service. | `internal` | No | | `DeployRoute53Record` | Set to true for deploying a Route 53 record with the given DNS record name for routing traffic to the LoadBalancer. | `true` | No | | `HostedZoneId` | ID of the hosted zone for configuring routing to TLS Listener | | No | | `DNSRecordName` | Name of the DNS record to be created for configuring routing to TLS Listener | | No | | `ListenerCertificateArn` | ARN of the certificate in AWS Certificate Manager to be used by the listeners. This is required when the load balancer should accept HTTPS/TLS connections from agents. | | No | | `TLSPrivateKeyArn` | AWS Secret Manager ARN of the private key to be used by port 5443. The container will use this secret to start the HTTPS listener of Traceable Platform Agent, which can then be used for TLS re-encryption from LoadBalancer to Traceable Platform Agent in case of ALB or TLS passthrough in case of NLB. | | No | | `TLSCertificateArn` | AWS Secret Manager ARN of the certificate to be used by port 5443. The container will use this secret to start the HTTPS listener of Traceable Platform Agent which can then be used for TLS re-encryption from LoadBalancer to Traceable Platform Agent in case of ALB or TLS passthrough in case of NLB. | | No | | `EnabledPorts` | List of ports to be enabled. If loadbalancing is enabled HTTP/1 and HTTP/2 would be fronted by an ALB, and other TCP connection ports would be fronted by an NLB | 5442 | No | | `EnableDefaultLogging` | Set this flag to true for enabling logging to AWS Cloudwatch | true | Yes | 7. Click **Next**. 8. **Configure stack options:** 1. Configure additional stack options such as tags, permissions, advanced options, etc., as needed. 2. Click **Next**. 9. **Review and create**: 1. Review the stack details and parameters to ensure everything is correct. 2. Acknowledge the creation of IAM resources, if applicable, by checking the box at the bottom. 3. Click **Create Stack**. 10. **Monitor stack creation:** 1. CloudFormation will begin creating the stack. You can monitor the progress on the **Events** tab of the stack details page. 2. Wait for the stack creation to complete. This may take several minutes. 11. **Verify the deployment**: 1. Once the stack creation is complete, verify the resources created: - Check the ECS service and task definitions. - Verify the load balancer configurations (ALB/NLB). - Ensure the Route53 DNS records are correctly configured, if applicable. --- ## Option 2 — Install through AWS CLI Complete the following steps to deploy the Traceable Platform agent through AWS CLI using the template file: 1. **Prepare the template and parameters file**: 1. Ensure your ECS CloudFormation template file (`traceable-agent.yaml`) is ready and accessible. 2. Create a JSON file (for example `parameters.json`) containing the template's required parameters. Example `parameters.json`: ```json [  {    "ParameterKey": "CPU",    "ParameterValue": "2"  },  {    "ParameterKey": "Memory",    "ParameterValue": "8"  },  {    "ParameterKey": "TraceableRefreshToken",    "ParameterValue": "your-refresh-token"  },  {    "ParameterKey": "TraceableRefreshTokenArn"    "ParameterValue": "arn:aws:secretsmanager:us-west-2:1234589012:secret:traceablePlatformRefreshToken-QZ9"  },  {    "ParameterKey": "TraceableEnvironment",    "ParameterValue": "production"  },  {    "ParameterKey": "TraceableRemoteEndpoint",    "ParameterValue": "api.traceable.ai:443"  },  {    "ParameterKey": "VpcId",    "ParameterValue": "vpc-xxxxxxxx"  },  {    "ParameterKey": "SubnetId",    "ParameterValue": "subnet-xxxxxxxx"  },  {    "ParameterKey": "LBSubnetIds",    "ParameterValue": "subnet-xxxxxxxx,subnet-yyyyyyyy"  },  {    "ParameterKey": "AgentRestrictedSrcIPRange",    "ParameterValue": "0.0.0.0/0"  },  {    "ParameterKey": "ECSClusterName",    "ParameterValue": "your-ecs-cluster"  },  {    "ParameterKey": "TaskExecutionRoleARN",    "ParameterValue": "arn:aws:iam::xxxxxxxx:role/your-role"  },  {    "ParameterKey": "ServiceDiscoveryNameSpace",    "ParameterValue": "traceable.ai"  },  {    "ParameterKey": "ECSLaunchType",    "ParameterValue": "EC2"  },  {    "ParameterKey": "AgentImage",    "ParameterValue": "your-docker-image-url"  },  {    "ParameterKey": "PublicIP",    "ParameterValue": "DISABLED"  },  {    "ParameterKey": "LoadBalancerScheme",    "ParameterValue": "internal"  },  {    "ParameterKey": "DeployRoute53Record",    "ParameterValue": "true"  },  {    "ParameterKey": "HostedZoneId",    "ParameterValue": "Zxxxxxxxxxxxxxxxxx"  },  {    "ParameterKey": "DNSRecordName",    "ParameterValue": "traceable.example.com"  },  {    "ParameterKey": "ListenerCertificateArn",    "ParameterValue": "arn:aws:acm:region:account-id:certificate/certificate-id"  },  {    "ParameterKey": "TLSPrivateKeyArn",    "ParameterValue": "arn:aws:acm:region:account-id:certificate/certificate-id"  },  {    "ParameterKey": "TLSCertificateArn",    "ParameterValue": "arn:aws:acm:region:account-id:certificate/certificate-id"  } ] ``` 2. **Create the stack** — Enter the following command to create the stack: ```plaintext aws cloudformation create-stack --stack-name TraceableECSStack --template-body file://traceable-agent.yaml --parameters file://parameters.json --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM ``` 3. **Monitor the stack creation** — Check the status of the stack creation with: ```plaintext aws cloudformation describe-stacks --stack-name TraceableECSStack ``` 4. **Update or delete the stack** — Enter the following commands based on the operation: - Update the stack — To update the stack, modify the `traceable-agent.yaml` or `parameters.json` file and run: ```plaintext aws cloudformation update-stack --stack-name TraceableECSStack --template-body file://tracable-agent.yaml --parameters file://parameters.json --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM ``` - Delete the stack — Enter the following command: ```plaintext aws cloudformation delete-stack --stack-name TraceableECSStack ``` 5. **Verify the deployment** — Once the stack creation is complete, verify the resources created: - Check the ECS service and task definitions. - Verify the load balancer configurations (ALB/NLB). - Ensure the Route53 DNS records are correctly configured, if applicable. Amazon Route 53 is a scalable and highly available Domain Name System (DNS) web service provided by Amazon Web Services (AWS). It is designed to route end users to Internet applications by translating human-readable domain names, such as example.com, into IP addresses that computers can understand.