New Relic's ECS integration reports and displays performance data from your Amazon ECS environment.
Install overview
Before you install our ECS integration, we recommend reviewing the requirements. During the install process:
For EC2 and EXTERNAL (ECS Anywhere) 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 EC2 instances of the cluster. The infrastructure agent then monitors ECS and Docker containers.For AWS Fargate launch type: The infrastructure agent (
newrelic-infra
) gets deployed as a sidecar in every task to monitor. The AWS Fargate documentation defines a sidecar as a way to move part of a service's core responsibility into a containerized module that is deployed alongside the core application.
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 EC2, EXTERNAL (ECS Anywhere) and AWS Fargate launch types:
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 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.
Follow the additional instructions for your launch type:
Next steps:
- 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.
Install with automatic script
One install option is using our install script. To use the automatic install script:
Download the ECS integration installer:
curl -O https://download.newrelic.com/infrastructure_agent/integrations/ecs/newrelic-infra-ecs-installer.shAdd execute permissions to the installer:
chmod +x newrelic-infra-ecs-installer.shExecute it with
-h
to see the documentation and requirements:./newrelic-infra-ecs-installer.sh -hCheck that your AWS profile points to the same region where your ECS cluster was created:
$ aws configure get regionus-east-1$ aws ecs list-clustersYOUR_CLUSTER_ARNSarn:aws:ecs:us-east-1:YOUR_AWS_ACCOUNT:cluster/YOUR_CLUSTERExecute the installer, specifying your license key and cluster name.
EC2 launch type:
./newrelic-infra-ecs-installer.sh -c YOUR_CLUSTER_NAME -l YOUR_LICENSE_KEYEXTERNAL (ECS Anywhere) launch type:
./newrelic-infra-ecs-installer.sh -c YOUR_CLUSTER_NAME -l YOUR_LICENSE_KEY -eAWS Fargate launch type:
./newrelic-infra-ecs-installer.sh -f -c YOUR_CLUSTER_NAME -l YOUR_LICENSE_KEYAdditional 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.jsonTip
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.
Next steps:
- 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.
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:
Check that your AWS profile points to the same region where your ECS cluster was created:
$ aws configure get regionus-east-1$ aws ecs list-clustersYOUR_CLUSTER_ARNSarn:aws:ecs:us-east-1:YOUR_AWS_ACCOUNT:cluster/YOUR_CLUSTERSave 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"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"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"Attach the policies
NewRelicSSMLicenseKeyReadAccess
, andAmazonECSTaskExecutionRolePolicy
to the role:aws iam attach-role-policy \--role-name "NewRelicECSTaskExecutionRole" \--policy-arn "POLICY_ARN"Choose your launch type for more instructions:
Next steps:
- Wait a few minutes and then look for your data in the UI.
- Recommended: Install our ECS cloud integration, a separate integration which gets you supplementary ECS data, including information about clusters and services.
- See recommended alert conditions.
- Understand the AWS resources created by this process.
Did this doc help with your installation?
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.
- Creates the service
- 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.
- Creates the service