• English日本語한국어
  • Log inStart now

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:

Install options

Choose the install you want:

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 .
    • 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:

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:

    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 and cluster name.

  6. Additional steps for the 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

      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:

    $ 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 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, 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:

When you're done, see Next steps.

Did this doc help with your installation?

Next steps after install

After you've installed this integration:

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 .
  • 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.
Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.