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: Our agent gets deployed onto an ECS cluster as a service using the daemon scheduling strategy (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, our agent gets deployed as a sidecar. Optional: 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 your desired region(s). 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.
   • For EC2 and External (ECS Anywhere) launch type: Registers the New Relic infrastructure ECS integration task.

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.

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 the just created NewRelicECSTaskExecutionRole needs to be used as the task execution role. Policies attached to the role (All launch types):

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

   • Then, you can add the container you want to monitor as a sidecar.

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 will 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.

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.
• Recommended: Install our 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. Policies attached to the role:
  • NewRelicSSMLicenseKeyReadAccess (created by the installer).
  • AmazonECSTaskExecutionRolePolicy
• Registers the newrelic-infra ECS task definition for EC2 and External (ECS Anywhere) launch types.
• For EC2 launch type, this is also done:
  • Creates the service newrelic-infra for the registered task using a daemon scheduling strategy and EC2 launch type.
• For EXTERNAL (ECS Anywhere) launch type, this is also done:
  • Creates the service newrelic-infra-external for the registered task using a daemon scheduling strategy and EXTERNAL (ECS Anywhere) launch type.