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 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:

  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

• Java

• Go

• .NET

• Python

• Node.js

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:

      [
        {
          "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:

   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:

   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:

     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:

     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.