- 27 Aug 2024
- 8 Minutes to read
- Print
- PDF
Install using CloudFormation
- Updated on 27 Aug 2024
- 8 Minutes to read
- Print
- PDF
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 totrue
,HostedZoneId
andDNSRecordName
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
, andTLSCertificateArn
are mandatory fields. TheTLSPrivateKeyArn
andTLSCertificateArn
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
, andTLSCertificateArn
are required). For more information, see the table below.
OTLP-based agent configuration
These configurations apply to the following OTLP-based tracing agents:
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
, andTLSCertificateArn
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:
Open your web browser and log in to the AWS Management Console.
In the AWS Management Console, navigate to the CloudFormation service.
Click on Create stack and then choose With new resources (standard).
Specify the template:
Select "Upload a template file" and then click on "Choose file" to upload your ECS CloudFormation template file (
traceable-agent.yaml
).Click Next.
Enter a stack name (for example,
TraceableECSStack
).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 NLB5442
No
EnableDefaultLogging
Set this flag to true for enabling logging to AWS Cloudwatch
true
Yes
Click Next.
Configure stack options:
Configure additional stack options such as tags, permissions, advanced options, etc., as needed.
Click Next.
Review and create:
Review the stack details and parameters to ensure everything is correct.
Acknowledge the creation of IAM resources, if applicable, by checking the box at the bottom.
Click Create Stack.
Monitor stack creation:
CloudFormation will begin creating the stack. You can monitor the progress on the Events tab of the stack details page.
Wait for the stack creation to complete. This may take several minutes.
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.
Option 2 — Install through AWS CLI
Complete the following steps to deploy the Traceable Platform agent through AWS CLI using the template file:
Prepare the template and parameters file:
Ensure your ECS CloudFormation template file (
traceable-agent.yaml
) is ready and accessible.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" } ]
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
Monitor the stack creation — Check the status of the stack creation with:
aws cloudformation describe-stacks --stack-name TraceableECSStack
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
orparameters.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
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.