> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap/installation/platform-agent/ecs/ecs.md).

# ECS

The topic covers installing and configuring Traceable agent using a custom `docker-compose.ym`l file. You also need to configure a few parameters in the `ecs-params.ym`l 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_CLI_installation.html).
* 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** (<i class="fa-gear">:gear:</i>) → **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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-cli-tutorial-fargate.html). 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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-cli-tutorial-fargate.html). 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:

```bash
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.

```yaml
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:

```yaml
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:

| Parameter                                                                                                                                                               | Description                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><strong>Ports</strong></p><p>Configure the following port numbers for traceable-agent:</p><ul><li>5441</li><li>5442</li><li>4317</li><li>9411</li><li>8181</li></ul> | <p>The ports for traceable-agent are for:</p><ul><li>traceable-agent GRPC</li><li>traceable-agent REST</li><li>OpenTelemetry (OTLP)</li><li>Zipkin HTTP</li><li>Open Policy Agent (OPA)</li></ul> |
| TA\_REFRESH\_TOKEN                                                                                                                                                      | Use the token generated in the [Prerequisite ](#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:

```
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](https://docs.amazonaws.cn/en_us/AmazonECS/latest/developerguide/cmd-ecs-cli-compose.html).

***

## **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:

```hcl
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
}
```

{% @harness-feedback/feedback %}