Install the ECS integration

New Relic's ECS integration reports and displays performance data from your Amazon ECS environment.

Install overview

Before you install, it may help you to understand at a high level how our infrastructure agent (newrelic-infra) is deployed for these two launch types:

• EC2 and EXTERNAL (ECS Anywhere) launch type: The daemon scheduling strategy deploys our agent onto an ECS cluster as a service (explained here in the AWS docs). This installs the agent in all EC2 instances of the cluster, and it then monitors ECS and Docker containers.

• AWS Fargate launch type: In every task to monitor, you deploy our agent as a sidecar. You can optionally learn more about how AWS defines a sidecar.

Install options

Choose the install you want:

• Install using AWS CloudFormation
• Install using automatic script
• Install manually

Install using CloudFormation

To help you install using AWS CloudFormation, we provide some CloudFormation templates that install the ECS integration onto your AWS account for EC2, EXTERNAL (ECS Anywhere), and AWS Fargate launch types.

To install using CloudFormation:

1. To register the ECS integration task, deploy this stack. Ensure you're deploying the stack to one or more of your desired regions. This stack creates the following resources:

   • A secret that stores the New Relic license key.
   • A policy to access the license key.
   • An instance role to be used as an ECS task ExecutionRole, with access to the license key.
   • A registration of the New Relic infrastructure ECS integration task, for EC2 and External (ECS Anywhere) launch type.

2. Follow the additional instructions for your launch type:

   EC2 launch type

   To create a service that runs the task on every EC2 container instance, deploy this stack.

   Select EC2 Launch type. Then a Service named newrelic-infra will be created in the cluster.

   External (ECS Anywhere) launch type

   To create a service that runs the task on every external container instance, deploy this stack.

   Select EXTERNAL Launch type. Then a Service named newrelic-infra-external will be created in the cluster.

   AWS Fargate launch type

   1. Download the task definition example with the sidecar container to be deployed:

      bash

      Copy

      $
      curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-fargate-example-latest.json

      Tip

      For Graviton, replace "cpuArchitecture": "X86_64" with "cpuArchitecture": "ARM64".

   2. Add the newrelic-infra container in this task definition as a sidecar to the task definitions you want to monitor. In this example task, your application's containers replace the placeholder busybox container.

      Configure NRIA_IS_FORWARD_ONLY for Fargate

      When deploying the New Relic infrastructure agent as a sidecar in Fargate environments, you must set the NRIA_IS_FORWARD_ONLY environment variable to true. This is a critical configuration for proper operation in serverless Fargate deployments.

      Why this setting is required:

   • Prevents incorrect host entity creation: Fargate is serverless and AWS manages the underlying compute resources. Without this setting, the infrastructure agent may attempt to create host entities for non-existent infrastructure.

   • Avoids billing discrepancies: Entity-based metering charges customers based on the number of monitored entities. Incorrect host entity creation causes billing issues.

   • Enables proper APM-to-Container linking: This setting ensures that APM applications are correctly linked to Container entities rather than synthetic Host entities.

     This example task definition includes the required Fargate configuration:

     {
       "family": "newrelic-infra-fargate",
       "networkMode": "awsvpc",
       "requiresCompatibilities": ["FARGATE"],
       "cpu": "256",
       "memory": "512",
       "containerDefinitions": [
         {
           "name": "newrelic-infra",
           "image": "newrelic/nri-ecs:latest",
           "essential": false,
           "environment": [
             {
               "name": "NRIA_IS_FORWARD_ONLY",
               "value": "true"
             },
             {
               "name": "NRIA_LICENSE_KEY",
               "value": "your-license-key"
             },
             {
               "name": "NRIA_PASSTHROUGH_ENVIRONMENT",
               "value": "ECS_CONTAINER_METADATA_URI,ECS_CONTAINER_METADATA_URI_V4,FARGATE"
             },
             {
               "name": "FARGATE",
               "value": "true"
             }
           ]
         },
         {
           "name": "your-application",
           "image": "your-app-image:latest",
           "essential": true
         }
       ]
     }

     Copy

     Important

     The NRIA_IS_FORWARD_ONLY=true environment variable is required for all Fargate deployments. Omitting this setting can result in:

     • Incorrect host entity creation

     • APM-to-Container relationship failures

     • Billing discrepancies due to unexpected entity counts

       If you download the example task definition, verify that this environment variable is present and set to true.

   3. Register the task definition:

      bash

      Copy

      $
      aws ecs register-task-definition --cli-input-json file://newrelic-infra-ecs-fargate-example-latest.json

   4. Create a service or run a task using this task definition.

When you're done, see Next steps.

Install with automatic script

One install option is using our install script. To use the automatic install script:

1. Download the ECS integration installer:

   bash

   Copy

   $
   curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-installer.sh

2. Add execute permissions to the installer:

   bash

   Copy

   $
   chmod +x newrelic-infra-ecs-installer.sh

3. Execute it with -h to see the documentation and requirements:

   bash

   Copy

   $
   ./newrelic-infra-ecs-installer.sh -h

4. Check that your AWS profile points to the same region where your ECS cluster was created:

   bash

   Copy

   $
   aws configure get region
   us-east-1
   $
   
   $
   aws ecs list-clusters
   YOUR_CLUSTER_ARNS  
   arn:aws:ecs:us-east-1:YOUR_AWS_ACCOUNT:cluster/YOUR_CLUSTER

5. Execute the installer, specifying your license key and cluster name.

   EC2 launch type

   bash

   Copy

   $
   ./newrelic-infra-ecs-installer.sh -c YOUR_CLUSTER_NAME -l YOUR_LICENSE_KEY

   External (ECS Anywhere) launch type

   bash

   Copy

   $
   ./newrelic-infra-ecs-installer.sh -c YOUR_CLUSTER_NAME -l YOUR_LICENSE_KEY -e

   AWS Fargate launch type

   bash

   Copy

   $
   ./newrelic-infra-ecs-installer.sh -f -c YOUR_CLUSTER_NAME -l YOUR_LICENSE_KEY

6. Additional steps for the Fargate launch type (not EC2 launch type):

   • Download the task definition example with the sidecar container to be deployed:

     bash

     Copy

     $
     curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-fargate-example-latest.json

     Tip

     For Graviton, replace "cpuArchitecture": "X86_64" with "cpuArchitecture": "ARM64".

     Notice that you must use the role you just created, NewRelicECSTaskExecutionRole, as the task execution role.

     This role includes the following policies for all launch types:

     • NewRelicSSMLicenseKeyReadAccess which enables access to the SSM parameter with the license key.
     • AmazonECSTaskExecutionRolePolicy

   • Add the container you want to monitor as a sidecar.

   Important

   When using AWS Fargate, you must also ensure the sidecar container has the environment variable NRIA_IS_FORWARD_ONLY set to true inside your task definition. Refer to the Fargate setup instructions under CloudFormation for configuration details and why this setting is critical.

When you're done, see Next steps.

Manual install

One install option is to manually do the steps that are done by the automatic installer script. We'll describe how this is done using the awscli tool:

1. Check that your AWS profile points to the same region where your ECS cluster was created:

   bash

   Copy

   $
   aws configure get region
   us-east-1
   $
   
   $
   aws ecs list-clusters
   YOUR_CLUSTER_ARNS
   arn:aws:ecs:us-east-1:YOUR_AWS_ACCOUNT:cluster/YOUR_CLUSTER

2. Save your license key as a Systems Manager (SSM) parameter:

   bash

   Copy

   $
   aws ssm put-parameter \
   >
     --name "/newrelic-infra/ecs/license-key" \
   >
     --type SecureString \
   >
     --description 'New Relic license key for ECS monitoring' \
   >
     --value "NEW_RELIC_LICENSE_KEY"

3. Create an IAM policy to access the license key parameter:

   bash

   Copy

   $
   aws iam create-policy \
   >
     --policy-name "NewRelicSSMLicenseKeyReadAccess" \
   >
     --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":["ssm:GetParameters"],"Resource":["ARN_OF_LICENSE_KEY_PARAMETER"]}]}' \
   >
     --description "Provides read access to the New Relic SSM license key parameter"

4. Create an IAM role to be used as the task execution role:

   bash

   Copy

   $
   aws iam create-role \
   >
     --role-name "NewRelicECSTaskExecutionRole" \
   >
     --assume-role-policy-document '{"Version":"2008-10-17","Statement":[{"Sid":"","Effect":"Allow","Principal":{"Service":"ecs-tasks.amazonaws.com"},"Action":"sts:AssumeRole"}]}' \
   >
     --description "ECS task execution role for New Relic infrastructure"

5. Attach the policies NewRelicSSMLicenseKeyReadAccess and AmazonECSTaskExecutionRolePolicy to the role:

   bash

   Copy

   $
   aws iam attach-role-policy \
   >
     --role-name "NewRelicECSTaskExecutionRole" \
   >
     --policy-arn "POLICY_ARN"

6. Choose your launch type for more instructions:

   EC2 and External (ECS Anywhere) launch type

   Additional steps for EC2 launch type:

   1. Download the New Relic ECS integration task definition template file:

      bash

      Copy

      $
      curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-ec2-latest.json

   2. Replace the task execution role in the template file with the newly created role:

      "executionRoleArn": "NewRelicECSTaskExecutionRole",

      Copy

   3. Replace the valueFrom attribute of the secret with the name of the Systems Manager parameter:

      "secrets": [
        {
          "valueFrom": "/newrelic-infra/ecs/license-key",
          "name": "NRIA_LICENSE_KEY"
        }
      ],

      Copy

   4. Register the task definition file:

      bash

      Copy

      $
      aws ecs register-task-definition --cli-input-json file://newrelic-infra-ecs-ec2-latest.json

   5. Create a service with the daemon scheduling strategy for the registered task:

      For EC2 launch type:

      bash

      Copy

      $
      aws ecs create-service --cluster "YOUR_CLUSTER_NAME" --service-name "newrelic-infra" --task-definition "newrelic-infra" --scheduling-strategy DAEMON --launch-type EC2

      For EXTERNAL (ECS Anywhere) launch type:

      bash

      Copy

      $
      aws ecs create-service --cluster "YOUR_CLUSTER_NAME" --service-name "newrelic-infra-external" --task-definition "newrelic-infra" --scheduling-strategy DAEMON --launch-type EXTERNAL

   AWS Fargate launch type

   Additional steps for the AWS Fargate launch type:

   1. Download the task definition example with the sidecar container to be deployed:

      bash

      Copy

      $
      curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-fargate-example-latest.json

      Tip

      For Graviton, replace "cpuArchitecture": "X86_64" with "cpuArchitecture": "ARM64".

   2. Add the newrelic-infra container in this task definition as a sidecar to the task definitions you want to monitor. In this example task, your application's containers replace the placeholder busybox container.

      Important

      Ensure that you configure the environment variable NRIA_IS_FORWARD_ONLY to true in your manually edited task definition sidecar container settings. Refer to the CloudFormation Fargate section for detailed instructions and a full JSON example.

When you're done, see Next steps.

Next steps after install

After you've installed this integration:

• Wait a few minutes and then look for your data in the UI.
• Install our recommended ECS cloud integration, which gets you other ECS data, including information about clusters and services.
• See recommended alert conditions.
• Understand the AWS resources created by this process.

AWS resources created

When you install the ECS integration using default/recommended values, it does the following in AWS:

• Creates Systems Manager (SSM) parameter /newrelic-infra/ecs/license-key. This system parameter contains the New Relic license key.
• Creates IAM policy NewRelicSSMLicenseKeyReadAccess, which enables access to the SSM parameter with the license key.
• Creates IAM role NewRelicECSTaskExecutionRole used as the task execution role. This role includes the following policies:
  • NewRelicSSMLicenseKeyReadAccess (created by the installer).
  • AmazonECSTaskExecutionRolePolicy
• Registers the newrelic-infra ECS task definition for EC2 and External (ECS Anywhere) launch types.
• Creates the following for EC2 launch type:
  • The service newrelic-infra for the registered task, using a daemon scheduling strategy and EC2 launch type.
• Creates the following for EXTERNAL (ECS Anywhere) launch type:
  • The service newrelic-infra-external for the registered task, using a daemon scheduling strategy and EXTERNAL (ECS Anywhere) launch type.