Install using CloudFormation
  • 27 Aug 2024
  • 8 Minutes to read
  • PDF

Install using CloudFormation

  • PDF

Article summary

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:

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.


Was this article helpful?

What's Next