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

    Install using CloudFormation

    • Updated on 27 Aug 2024
    • 8 Minutes to read
    • Print
    • 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
    ©2023 Traceable Inc
    terms of services
    privacy policy
    oss disclosures