Install the ECS integration

New Relic's ECS integration reports and displays performance data from your Amazon ECS environment. This document explains how to install this integration.

Install overview

Before you install our ECS integration, we recommend reviewing the requirements.

Here's a brief overview of what happens during the install process:

  • For EC2 launch type:

    • The infrastructure agent (newrelic-infra) gets deployed onto an ECS cluster as a service using the daemon scheduling strategy.
    • This deployment installs the infrastructure agent in all the container instances of the cluster. The infrastructure agent then monitors ECS and Docker containers.
  • For Fargate launch type:

    • The infrastructure agent (newrelic-infra) gets deployed as a sidecar in every task to monitor.

Install options:

Install using CloudFormation

One install option is using AWS CloudFormation. We provide some CloudFormation templates that install the ECS integration onto your AWS account for both EC2 and Fargate launch types:

  1. To register the New Relic's 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 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 launch type: Registers the New Relic Infrastructure ECS integration task.
  2. Follow the additional instructions for your launch type:
    EC2 launch type

    Additional steps for EC2 launch type:

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

    Fargate launch type

    Additional steps for Fargate launch type:

    1. Download the task definition example with the sidecar container to be deployed:
      curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-fargate-example-latest.json
      
    2. Add the newrelic-infra container in this task definition as a sidecar to the task definitions you want monitored.

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:
    curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-installer.sh
    
  2. Add execute permissions to the installer:
    chmod +x newrelic-infra-ecs-installer.sh
    
  3. Execute it with -h to see the documentation and requirements:
    ./newrelic-infra-ecs-installer.sh -h
    
  4. Check that your AWS profile points to the same region where your ECS cluster was created:
    $ 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:

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

    Fargate launch type:

    ./newrelic-infra-ecs-installer.sh -fargate -c YOUR_CLUSTER_NAME -l YOUR_LICENSE_KEY
    
  6. Additional steps for Fargate launch type (not EC2 launch type):
    • Download the task definition example with the sidecar container to be deployed:
      curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-fargate-example-latest.json
    • Add the single container in this task definition as a sidecar to the task definitions you want monitored.

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:
    $ 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 New Relic license key as a Systems Manager (SSM) parameter:
    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:
    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:
    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, AmazonEC2ContainerServiceforEC2Role, and AmazonECSTaskExecutionRolePolicy to the role:
    aws iam attach-role-policy \
      	--role-name "NewRelicECSTaskExecutionRole" \
      	--policy-arn "POLICY_ARN"
    
  6. Choose your launch type for more instructions:
    EC2 launch type

    Additional steps for EC2 launch type:

    1. Download the New Relic ECS integration task definition template file:
      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",
      
    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"
        }
      ],
      
    4. Register the task definition file:
      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:
      aws ecs create-service --cluster "YOUR_CLUSTER_NAME" --service-name "newrelic-infra" --task-definition "newrelic-infra" --scheduling-strategy DAEMON 
      
    Fargate launch type

    Additional steps for the Fargate launch type:

    1. Download the task definition example with the sidecar container to be deployed:
      curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-fargate-example-latest.json
      
    2. Add the newrelic-infra container in this task definition as a sidecar to the task definitions you want monitored.

Next steps:

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

    • AmazonEC2ContainerServiceforEC2Role

    • AmazonECSTaskExecutionRolePolicy

  • For EC2 launch type, this is also done:
    • Registers the newrelic-infra ECS task definition.
    • Creates the service newrelic-infra for the registered task using a daemon scheduling strategy.

For more help

If you need more help, check out these support and learning resources: