ECS EC2 - Install | SigNoz Docs

This guide explains how to install the ECS EC2 Collection Agent on an Amazon ECS cluster with Foundry and Terraform.

Prerequisites

An Amazon ECS cluster with EC2 container instances or ECS Anywhere external instances, running Docker Engine 25 or newer.
Terraform 1.4 or newer and the AWS CLI on the same machine, with AWS credentials that can create ECS services, task definitions, IAM roles, and AWS AppConfig applications.
A SigNoz to send data to: SigNoz Cloud or a self-hosted SigNoz.

Install the Collection Agent

Foundry is an open-source CLI that runs your self-hosted observability stack as code. One declarative config provisions the infrastructure, installs the SigNoz backend, and sets up OpenTelemetry collection on bare metal, containers, or Kubernetes. Learn more about Foundry.

Step 1: Install foundryctl

Run this on the machine where you run Terraform:

curl -fsSL https://signoz.io/foundry.sh | bash

For manual install (Windows PowerShell, air-gapped, etc.) or PATH setup, see the foundry getting-started guide.

Step 2: Create casting.yaml

Create a file named casting.yaml with one document for the collector described in How it works. collector.kind: agent selects that collector. Pick the tab for the instances your cluster runs on:

Most steps are identical. To adapt this guide, update the endpoint and remove the ingestion key as shown in Cloud → Self-Hosted.

apiVersion: v1alpha1
kind: CollectionAgent
metadata:
  name: signoz
  annotations:
    foundry.signoz.io/ecs-region: <aws-region>
    foundry.signoz.io/ecs-cluster-arn: <ecs-cluster-arn>
spec:
  deployment:
    platform: aws
    mode: ecs
    flavor: terraform
  collector:
    kind: agent
    spec:
      env:
        SIGNOZ_INGESTION_ENDPOINT: https://ingest.<region>.signoz.cloud:443
        SIGNOZ_INGESTION_KEY: <your-ingestion-key>
        OTEL_RESOURCE_ATTRIBUTES: deployment.environment=<DEPLOYMENT_ENVIRONMENT>
      config:
        data:
          collector/agent/agent.yaml: |
            exporters:
              otlphttp/signoz:
                headers:
                  signoz-ingestion-key: ${env:SIGNOZ_INGESTION_KEY}

Verify these values:

<aws-region>: The AWS region of your ECS cluster, for example us-east-1.
<ecs-cluster-arn>: The ARN of your ECS cluster, from the Amazon ECS console or aws ecs list-clusters.
<region>: Your SigNoz Cloud region.
<your-ingestion-key>: Your SigNoz Cloud ingestion key.
<DEPLOYMENT_ENVIRONMENT>: Your deployment environment, for example staging or production. It becomes deployment.environment on the collected telemetry.

For every option of this casting, see the ECS EC2 Terraform example.

Outbound access from each instance to AWS AppConfig, public.ecr.aws, Docker Hub, and your SigNoz endpoint.
Task IAM roles enabled for the host network mode, which the ECS Anywhere install script sets up.

This casting runs the collector with the EXTERNAL launch type, detects the host with the system detector, and also collects /var/log/syslog and /var/log/auth.log:

apiVersion: v1alpha1
kind: CollectionAgent
metadata:
  name: signoz
  annotations:
    foundry.signoz.io/ecs-region: <aws-region>
    foundry.signoz.io/ecs-cluster-arn: <ecs-cluster-arn>
spec:
  deployment:
    platform: aws
    mode: ecs
    flavor: terraform
  collector:
    kind: agent
    spec:
      env:
        SIGNOZ_INGESTION_ENDPOINT: https://ingest.<region>.signoz.cloud:443
        SIGNOZ_INGESTION_KEY: <your-ingestion-key>
        OTEL_RESOURCE_ATTRIBUTES: deployment.environment=<DEPLOYMENT_ENVIRONMENT>
      config:
        data:
          collector/agent/agent.yaml: |
            exporters:
              otlphttp/signoz:
                headers:
                  signoz-ingestion-key: ${env:SIGNOZ_INGESTION_KEY}
            processors:
              resourcedetection:
                detectors: [env, system]
            receivers:
              filelog/host:
                include:
                  - /hostfs/var/log/messages
                  - /hostfs/var/log/secure
                  - /hostfs/var/log/syslog
                  - /hostfs/var/log/auth.log
                  - /hostfs/var/log/ecs/*.log
  patches:
    - target: collectionagent/collector/agent/collector.tf.json
      operations:
        - op: replace
          path: /resource/aws_ecs_task_definition/collector_agent/requires_compatibilities/0
          value: EXTERNAL
        - op: replace
          path: /resource/aws_ecs_service/collector_agent/launch_type
          value: EXTERNAL

Verify these values:

<aws-region>: The AWS region of your ECS cluster, for example us-east-1.
<ecs-cluster-arn>: The ARN of the ECS cluster your external instances are registered to, from the Amazon ECS console or aws ecs list-clusters.
<region>: Your SigNoz Cloud region.
<your-ingestion-key>: Your SigNoz Cloud ingestion key.
<DEPLOYMENT_ENVIRONMENT>: Your deployment environment, for example staging or production. It becomes deployment.environment on the collected telemetry.

For every option of this casting, see the ECS EC2 Terraform example.

Annotations under metadata set the region and ECS cluster the collector runs on, and the IAM roles its task uses. To use a role you manage instead of the one Terraform creates, add its annotation. The casting reads these:

metadata:
  name: signoz
  annotations:
    foundry.signoz.io/ecs-region: <aws-region>                                 # AWS region of the cluster, required
    foundry.signoz.io/ecs-cluster-arn: <ecs-cluster-arn>                       # ECS cluster the collector runs on, required
    foundry.signoz.io/ecs-task-role-arn: <task-role-arn>                       # optional; Terraform creates signoz-collectionagent-iam-task when absent
    foundry.signoz.io/ecs-task-execution-role-arn: <task-execution-role-arn>   # optional; Terraform creates signoz-collectionagent-iam-exec when absent

Verify these values:

<aws-region> and <ecs-cluster-arn>: The values you set in the casting above.
<task-role-arn>: An IAM role with appconfig:StartConfigurationSession and appconfig:GetLatestConfiguration, used to fetch the collector config.
<task-execution-role-arn>: An IAM role that pulls the images and starts the task, for example one with the AmazonECSTaskExecutionRolePolicy managed policy.

Terraform attaches policies to the roles it creates and passes the task's roles to ECS. Your AWS credentials need permission for both: iam:PutRolePolicy and iam:AttachRolePolicy to attach the policies, and iam:PassRole to pass the roles.

The example's annotations table describes each one.

The Collection Agent's Terraform state starts in pours/collectionagent/collector/agent/terraform.tfstate. To keep it in an S3 bucket, add this under the Collection Agent document's spec before the first cast:

spec:
  patches:
    - target: collectionagent/collector/agent/backend.tf.json
      operations:
        - op: replace
          path: /terraform/backend
          value:
            s3:
              bucket: <state-bucket>
              key: signoz/collectionagent.tfstate
              region: <state-bucket-region>

Verify these values:

<state-bucket>: An existing S3 bucket. Your AWS credentials need s3:ListBucket, s3:GetObject and s3:PutObject on it.
<state-bucket-region>: The AWS region of that bucket, for example us-east-1.

If you add the backend after a first cast, run this from the directory that contains casting.yaml to move the existing state into the bucket, then cast again:

foundryctl forge -f casting.yaml
terraform -chdir=pours/collectionagent/collector/agent init -migrate-state

Step 3: Deploy

Run this from the directory that contains casting.yaml:

foundryctl cast -f casting.yaml

This command:

writes the Terraform root pours/collectionagent/collector/agent;
applies it with Terraform, using the AWS credentials on this machine;
creates the collector's config in AWS AppConfig, the signoz-collector-agent task definition and daemon service, and the default IAM roles ( if not specified).

To run Terraform directly, generate the Terraform root and apply it. Run this from the directory that contains casting.yaml:

foundryctl forge -f casting.yaml   # writes the Terraform root under pours/collectionagent/collector/agent
terraform -chdir=pours/collectionagent/collector/agent init
terraform -chdir=pours/collectionagent/collector/agent apply

To see the changes before you apply them, run terraform -chdir=pours/collectionagent/collector/agent plan.

Step 4: Verify the Collection Agent

Run this on the machine where you use the AWS CLI to check that the daemon service runs one collector task on every instance:

aws ecs describe-services --region <aws-region> --cluster <ecs-cluster-arn> \
  --services signoz-collector-agent \
  --query 'services[0].{status:status,desiredCount:desiredCount,runningCount:runningCount}'

Verify these values:

<aws-region>: The foundry.signoz.io/ecs-region value in casting.yaml.
<ecs-cluster-arn>: The foundry.signoz.io/ecs-cluster-arn value in casting.yaml.

The output should look similar to the following, with runningCount equal to desiredCount, the number of instances in the cluster. The counts vary:

{
    "status": "ACTIVE",
    "desiredCount": 3,
    "runningCount": 3
}

In SigNoz, open the Hosts view under Infrastructure Monitoring, which lists each instance under its host.name. Check Logs Explorer to confirm container and host logs are flowing; host logs show under service.name ecs-host.

Customize the Collection Agent

Every change follows the same loop: edit casting.yaml, then run foundryctl cast -f casting.yaml again.

Collector settings (image, environment): set them in the collector's spec (see spec fields). For example, to pin the collector image:
```
spec:
  collector:
    spec:
      image: otel/opentelemetry-collector-contrib:0.139.0
```

Collector config (receivers, processors, pipelines): add it under spec.collector.spec.config.data, keyed collector/agent/agent.yaml. It merges into the generated config (see custom config files). For example, to collect host metrics every 30s:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              hostmetrics:
                collection_interval: 30s

Terraform (task definition, service): add patches under spec.patches against the files under collectionagent/collector/agent/, such as collector.tf.json for the task definition and daemon service. To find the path to patch, run foundryctl forge -f casting.yaml and look in the generated files under pours/collectionagent/collector/agent/. For example, to reserve more memory for the collector:
```
spec:
  patches:
    - target: collectionagent/collector/agent/collector.tf.json
      operations:
        - op: replace
          path: /locals/containers_collector_agent/1/memoryReservation
          value: 1024
```
Each run regenerates the files under pours/, so keep every change in casting.yaml.

Troubleshooting

The collector task is not placed on an instance

In Step 4, runningCount stays below desiredCount. Run this on the machine where you use the AWS CLI to read the service's latest events:

aws ecs describe-services --region <aws-region> --cluster <ecs-cluster-arn> \
  --services signoz-collector-agent --query 'services[0].events[:5].message'

Verify these values:

<aws-region>: The foundry.signoz.io/ecs-region value in casting.yaml.
<ecs-cluster-arn>: The foundry.signoz.io/ecs-cluster-arn value in casting.yaml.

The events include service signoz-collector-agent was unable to place a task because no container instance met all of its requirements. The closest matching container-instance <container-instance-id> is already using a port required by your task.

Cause: another task on that instance holds host port 4317 or 4318, for example another OpenTelemetry Collector running as a daemon service. The task also uses port 13133 (the collector's health check) and port 2772 (the AppConfig agent) on the instance without reserving them. A process that holds one of those makes the container fail at start instead of blocking placement.

Fix: list the cluster's services with aws ecs list-services --region <aws-region> --cluster <ecs-cluster-arn>, then delete the service that holds the ports or move its ports. The daemon service places its task on that instance again on its own.

After the fix, the Step 4 command shows runningCount equal to desiredCount.

The AppConfig agent container never turns healthy

In the Step 4 command, runningCount stays below desiredCount. Run this on a container instance to see the AppConfig agent container's status:

docker ps -a --filter label=com.amazonaws.ecs.container-name=signoz-collector-appconfig-agent --format '{{.Status}}'

The status shows (unhealthy). To see the error it gets from AWS AppConfig, read its logs:

docker logs --since 10m $(docker ps -aq --filter label=com.amazonaws.ecs.container-name=signoz-collector-appconfig-agent | head -n 1)

Cause: the task has no AWS credentials that can read the config. Either the task role you stated with foundry.signoz.io/ecs-task-role-arn lacks appconfig:StartConfigurationSession and appconfig:GetLatestConfiguration, or task IAM roles are not enabled for the host network mode on the instance.

Fix: add both actions to the task role, or enable task IAM roles as External instance additional configuration describes. The daemon service replaces the unhealthy task on its own.

After the fix, the Step 4 command shows runningCount equal to desiredCount.

foundryctl cast rejects a patch

In Step 3, or after you add a patch from Customize the Collection Agent, foundryctl cast -f casting.yaml stops before it applies anything, with the message failed to apply patch for target "<target>". Its cause ends with doc is missing key: <path>: missing value or doc is missing path: <path>: missing value, or, when no generated file matches the target, patch target "<target>" did not match any generated material.

Cause: the patch's target or path does not exist in what Foundry generates.

Fix: remove the patch and run foundryctl forge -f casting.yaml. Then take the target and the path from the generated files under pours/collectionagent/collector/agent/, add the patch back, and run Step 3 again.

After the fix, the cast creates the resources, and the Step 4 command shows the service.

terraform plan rejects the region or the cluster ARN

In Step 3, foundryctl cast -f casting.yaml stops at terraform plan with Error: Invalid value for variable and one of these messages:

aws_region must be a region identifier such as us-east-1.
cluster_arn must be the ARN of an ECS cluster.

Cause: the foundry.signoz.io/ecs-region or foundry.signoz.io/ecs-cluster-arn annotation is missing or malformed. The region must look like us-east-1, and the cluster ARN must start with arn:aws:ecs:. A role annotation that is not an IAM role ARN fails the same way.

Fix: set the annotation under metadata.annotations in casting.yaml, as in Step 2, then run Step 3 again.

After the fix, the cast creates the resources, and the Step 4 command shows the service.

terraform plan stops on an interpolation in `env`

In Step 3, foundryctl cast -f casting.yaml stops at terraform plan on collector.tf.json, in locals.containers_collector_agent[1].environment, with Error: Invalid reference for a value such as ${MY_KEY}, or Error: Extra characters after interpolation expression for a value such as ${env:MY_KEY}.

Cause: a value under spec.collector.spec.env contains ${, which Terraform reads as one of its own expressions.

Fix: replace the expression with the literal value in casting.yaml, then run Step 3 again.

After the fix, the cast creates the resources, and the Step 4 command shows the service.

terraform plan finds no AWS credentials

In Step 3, foundryctl cast -f casting.yaml stops at terraform plan with Error: No valid credential sources found.

Cause: Terraform's AWS provider found no credentials on the machine where you run foundryctl.

Fix: sign in with the AWS CLI or select a profile in the shell you run foundryctl from, for example:

export AWS_PROFILE=<profile-name>

Verify these values:

<profile-name>: A profile from aws configure list-profiles.

For every way to pass credentials, see the AWS provider authentication docs.

After the fix, aws sts get-caller-identity prints your account and role, and Step 3 gets past terraform plan.

Send data from your applications

Host metrics, container metrics, and container and host logs flow as soon as the collector is running. To send traces, metrics, and logs from your applications, see Send Data from Applications to the Collector.

ECS EC2 - Install

Prerequisites

Install the Collection Agent

Step 1: Install foundryctl

Step 2: Create casting.yaml

Step 3: Deploy

Step 4: Verify the Collection Agent

Customize the Collection Agent

Troubleshooting

The collector task is not placed on an instance

The AppConfig agent container never turns healthy

foundryctl cast rejects a patch

terraform plan rejects the region or the cluster ARN

terraform plan stops on an interpolation in env

terraform plan finds no AWS credentials

Send data from your applications

Next Steps

terraform plan stops on an interpolation in `env`