Search…
ECS
The topic covers installation and configuration of traceable-agent using a custom docker-compose.yml file. You also need to configure a few parameters in the ecs-params.yml file.

Prerequisite

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. If these are not turned on, then DNS resolution will not work when the Traceable proxy or sidecar tries to connect to the Traceable agent.
    Traceable Token - You need a valid Traceable token to complete the installation. Complete the following steps to generate a token:
    To generate the<TOKEN>, login to Traceable and click on Administration (
    ) > Access Token.
Traceable access 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.
1
ecs-cli up --cluster-config <CLUSTER_CONFIG> --ecs-profile <CLUSTER_PROFILE>
Copied!

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:
1
VPC created: vpc-xxxx
2
Subnet created: subnet-xxxx
3
Subnet created: subnet-xxxx
Copied!

Fetch the SECURITY_GROUPS

Enter the following command to fetch the security group:
1
aws ec2 describe-security-groups --filters Name=vpc-id,Values=<VPC_ID> --region <REGION>
Copied!

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:
1
ecs-cli configure --cluster <CLUSTER_NAME> --region <REGION> --default-launch-type <FARGATE|EC2> --config-name <CLUSTER_CONFIG_NAME>
Copied!
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:
1
ecs-cli configure profile --access-key <AWS_ACCESS_KEY_ID> --secret-key <AWS_SECRET_ACCESS_KEY> --profile-name <CLUSTER_PROFILE>
Copied!

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.
1
version: 1
2
task_definition:
3
ecs_network_mode: awsvpc # update if needed
4
5
task_execution_role: ecsTaskExecutionRole # update to the relevant task execution role
6
task_size:
7
mem_limit: 4096 # update if needed
8
cpu_limit: 2048 # update if needed
9
run_params:
10
network_configuration:
11
awsvpc_configuration:
12
subnets:
13
- "<Update>" # update
14
security_groups:
15
- "<Update>" # update
16
assign_public_ip: ENABLED
17
service_discovery:
18
private_dns_namespace:
19
name: traceableai
20
vpc: "<Update>" # update if needed
Copied!
Include public subnets in the$SUBNETS section of theecs-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:
1
version: '3'
2
services:
3
traceable-agent:
4
image: traceableai/traceable-agent:latest
5
command:
6
- "/traceable-agent"
7
- "--config=/conf/agent/agentconfig.yaml"
8
- "--pluginspath"
9
- "/plugins"
10
ports:
11
- "5441:5441" # GRPC
12
- "5442:5442" # HTTP
13
- "8181:8181" # OPA
14
- "4317:4317" # OTEL
15
- "9411:9411" # Zipkin HTTP
16
logging:
17
driver: awslogs
18
options:
19
awslogs-region: <update> # Update
20
awslogs-group: <update> #Update
21
awslogs-stream-prefix: traceable-platform # Update if needed
22
environment:
23
- TA_REFRESH_TOKEN=<update> # Update
24
- TA_ENVIRONMENT=<update> # Update
Copied!
The following table explains the various parameters of the docker-compose.yml file:
Parameter
Description
Ports
Configure the following port numbers for traceable-agent:
    5441
    5442
    4317
    9411
    8181
The ports for traceable-agent are for:
    traceable-agent GRPC
    traceable-agent REST
    OpenTelemetry (OTLP)
    Zipkin HTTP
    Open Policy Agent (OPA)
TA_REFRESH_TOKEN
Use the token generated in the Prerequisite section.
TA_ENVIRONMENT
Used to segregate environments in the Traceable dashboard, for example, development, QA, and so on.
Run the following command after ecs-params.yml and docker-compose.yml files are configured:
1
ecs-cli compose --project-name <PROJECT_NAME> service up --cluster-config <CLUSTER_CONFIG> --ecs-profile $CLUSTER_PROFILE --enable-service-discovery
Copied!
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:
1
ecs-cli compose --project-name traceable-agent service down
Copied!

Terraform

If you are managing your cluster with Terraform, here is an example task definition resource:
1
variable "log" {
2
description = "A log group to stream log data to"
3
type = string
4
default = "traceable-ecs"
5
}
6
7
resource "aws_cloudwatch_log_group" "traceable-log-group" {
8
name = var.log
9
10
tags = {
11
Environment = "${env}"
12
Application = "traceableai"
13
}
14
}
15
16
17
resource "aws_ecs_task_definition" "traceable-agent" {
18
family = "traceable-agent"
19
container_definitions = <<DEFINITION
20
[
21
{
22
"name": "traceable-agent",
23
"image": "traceableai/traceable-agent:latest",
24
"essential": true,
25
"logConfiguration": {
26
"logDriver": "awslogs",
27
"options": {
28
"awslogs-group": "${var.log}",
29
"awslogs-region": "${var.aws_region}",
30
"awslogs-stream-prefix": "ecs"
31
}
32
},
33
"command": ["/traceable-agent", "--config=/conf/agent/agentconfig.yaml", "--pluginspath", "/plugins"],
34
"portMappings": [
35
{
36
"hostPort": 5441,
37
"protocol": "tcp",
38
"containerPort": 5441
39
},
40
{
41
"hostPort": 5442,
42
"protocol": "tcp",
43
"containerPort": 5442
44
},
45
{
46
"hostPort": 4317,
47
"protocol": "tcp",
48
"containerPort": 4317
49
},
50
{
51
"hostPort": 9411,
52
"protocol": "tcp",
53
"containerPort": 9411
54
},
55
{
56
"hostPort": 8181,
57
"protocol": "tcp",
58
"containerPort": 8181
59
}
60
],
61
"environment": [
62
{
63
"name": "TA_REFRESH_TOKEN",
64
"value": "${var.token}"
65
},
66
{
67
"name": "TA_ENVIRONMENT",
68
"value": "${var.environment}"
69
},
70
{
71
"name": "GOGC",
72
"value": "80"
73
},
74
{
75
"name": "GODEBUG",
76
"value": "madvdontneed=1"
77
}
78
],
79
"memory": 100,
80
"cpu": 1
81
}
82
]
83
DEFINITION
84
}
85
86
Copied!

Next Steps

Last modified 1mo ago