ECS

The topic covers installing and configuring Traceable agent using a custom docker-compose.yml file. You also need to configure a few parameters in the ecs-params.yml file.

Before you begin

Read the following prerequisites before starting with installation:

• ECS CLI - For an ECS environment, the installation requires the use of ecs-cli. Make sure that ecs-cli is installed. For more information on ecs-cli, see Installing the Amazon ECS CLI.

• VPC, subnets, and security groups — Make a note of VPC, subnets, and security groups that will be used as part of the instrumentation process.

• DNS hostnames and resolutions — Make sure to turn on DNS hostnames and resolutions for the VPC that is used by the ECS cluster.

• Traceable Token - You need a valid Traceable token to complete the installation. Navigate to Settings()→ Account → Agent Token.

Set up your ECS environment

Setting up your ECS environment consists of the following:

• Creating a cluster

• Fetch VPC, subnet, and security groups

Create Cluster

Create a cluster using the ecs-cli. Follow the steps outlined in the AWS Docs. Step 3.1 from the AWS Docs will output the VPC and subnets. Save these because they will need to be reused in this tutorial. 

ecs-cli up --cluster-config <CLUSTER_CONFIG> --ecs-profile <CLUSTER_PROFILE>

Fetch VPC, SUBNET, and Security Groups

VPC and Subnet information is returned when you initially created the cluster with step 3.1 in the AWS Docs. The command returns something similar to:

VPC created: vpc-xxxx
Subnet created: subnet-xxxx
Subnet created: subnet-xxxx

Fetch the SECURITY_GROUPS

Enter the following command to fetch the security group:

aws ec2 describe-security-groups --filters Name=vpc-id,Values=<VPC_ID> --region <REGION>

Create cluster config and ECS CLI profile

Enter the following commands to create cluster-config and ecs-profile:

1. Configure an ECS cluster with a launch type, for example, ECS or FARGATE. Enter the following command:

ecs-cli configure --cluster <CLUSTER_NAME> --region <REGION> --default-launch-type <FARGATE|EC2> --config-name <CLUSTER_CONFIG_NAME>

For example, if your compute engine for ECS is FARGATE, then the value for default-launch-type would be FARGATE.

2. Configure an ECS CLI profile with your AWS access and secret key. Enter the following command:

ecs-cli configure profile --access-key <AWS_ACCESS_KEY_ID> --secret-key <AWS_SECRET_ACCESS_KEY> --profile-name <CLUSTER_PROFILE>

Install Traceable platform agent and side-car

Installing Traceable platform agent consists of the following:

• Configuring the ecs-params.yml file

• Configuring the docker-compose.yml file

Configure ecs-params.yml file

Based on your ECS environment, configure the ecs-params.yml file. Following is a sample ecs-params.yml file for installing the Traceable platform agent.

version: 1
task_definition:
  ecs_network_mode: awsvpc # update if needed

  task_execution_role: ecsTaskExecutionRole # update to the relevant task execution role
  task_size:
    mem_limit: 4096 # update if needed
    cpu_limit: 2048 # update if needed
run_params:
  network_configuration:
    awsvpc_configuration:
      subnets:
        - "<Update>" # update
      security_groups:
        - "<Update>" # update
      assign_public_ip: ENABLED
  service_discovery:
    private_dns_namespace:
      name: traceableai
      vpc: "<Update>" # update if needed

Include public subnets in the $SUBNETS section of the ecs-params.yml file.

Configure docker-compose.yml file

The docker-compose.yml file installs the traceable-agent service. The docker-compose file always fetches the latest version of the traceable-agent from Traceable’s docker hub repository. Following is a sample docker-compose.yml file:

version: '3'
services:
  traceable-agent:
    image: traceableai/traceable-agent:latest
    command:
      - "/traceable-agent"
      - "--config=/conf/agent/agentconfig.yaml"
      - "--pluginspath"
      - "/plugins"
    ports:
      - "5441:5441" # GRPC
      - "5442:5442" # HTTP
      - "8181:8181" # OPA
      - "4317:4317" # OTEL
      - "9411:9411" # Zipkin HTTP
    logging:
      driver: awslogs
      options:
        awslogs-region: <update> # Update
        awslogs-group: <update> #Update
        awslogs-stream-prefix: traceable-platform # Update if needed 
    environment:
      - TA_REFRESH_TOKEN=<update> # Update
      - TA_ENVIRONMENT=<update> # Update

The following table explains the various parameters of the docker-compose.yml file:

Run the following command after ecs-params.yml and docker-compose.yml files are configured:

ecs-cli compose --project-name <PROJECT_NAME> service up --cluster-config <CLUSTER_CONFIG> --ecs-profile $CLUSTER_PROFILE --enable-service-discovery

For more information about the various parameters of the command, see ecs-cli compose.

Shut down the service

If you want to shut down the service, enter the following command:

ecs-cli compose --project-name traceable-agent service down

Terraform

If you are managing your cluster with Terraform, here is an example task definition resource:

variable "log" {
    description = "A log group to stream log data to"
    type        = string
    default     = "traceable-ecs"
}

resource "aws_cloudwatch_log_group" "traceable-log-group" {
    name = var.log

    tags = {
        Environment = "${env}"
        Application = "traceableai"
    }
}


resource "aws_ecs_task_definition" "traceable-agent" {
    family                = "traceable-agent"
    container_definitions = <<DEFINITION
[
  {
    "name": "traceable-agent",
    "image": "traceableai/traceable-agent:latest",
    "essential": true,
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
        "awslogs-group": "${var.log}",
        "awslogs-region": "${var.aws_region}",
        "awslogs-stream-prefix": "ecs"
      }
    },
    "command": ["/traceable-agent", "--config=/conf/agent/agentconfig.yaml", "--pluginspath", "/plugins"],
    "portMappings": [
      {
        "hostPort": 5441,
        "protocol": "tcp",
        "containerPort": 5441
      },
      {
        "hostPort": 5442,
        "protocol": "tcp",
        "containerPort": 5442
      },
      {
        "hostPort": 4317,
        "protocol": "tcp",
        "containerPort": 4317
      },
      {
        "hostPort": 9411,
        "protocol": "tcp",
        "containerPort": 9411
      },
      {
        "hostPort": 8181,
        "protocol": "tcp",
        "containerPort": 8181
      }
    ],
    "environment": [
      {
        "name": "TA_REFRESH_TOKEN",
        "value": "${var.token}"
      },
      {
        "name": "TA_ENVIRONMENT",
        "value": "${var.environment}"
      },
      {  
        "name": "GOGC",
        "value": "80"
      },
      {
        "name": "GODEBUG",
        "value": "madvdontneed=1"
      }
    ],
    "memory": 100,
    "cpu": 1 
  }
]
DEFINITION
}