Management and configuration for Amazon Web Services cloud infrastructure is more robust and dynamic than ever before—especially given the capabilities of Amazon EC2 Systems Manager. At New Relic, we believe observability is a critical part of infrastructure management, and it turns out EC2 Systems Manager makes it easier than ever to install, update, or remove the New Relic Infrastructure agent when creating EC2 instances.

If you use—or plan to use—New Relic Infrastructure to monitor, gather metrics on, or help scale your EC2 infrastructure, this post is for you. I’ll show you how easy it is to install supported Linux and Windows Infrastructure agents onto your EC2 instances in just a few simple steps.

Rebranded New Relic logo

Inside Amazon EC2 Systems Manager

Amazon EC2 Systems Manager, available on the Amazon EC2 Dashboard, is tooling to configure and run management tasks on your EC2 infrastructure, whether that’s deployed in the AWS cloud or on-premise. With EC2 Systems Manager, you can, among other tasks, inspect your system’s inventory, patch vulnerabilities, and install additional tools—such as the Infrastructure agent into your infrastructure.

The Systems Manager agent that runs on your instances is called the Simple Systems Manager (SSM) agent, which is the main component I’ll refer to for the rest of this post.

Check out some great Amazon EC2 Systems Manager docs

I’m going to assume you already have an EC2 infrastructure. If you haven’t set up Systems Manager yet, follow the AWS documentation for getting set up, and note the Systems Manager prerequisites. Additionally, see Installing and Configuring SSM Agent on Windows Instances and Installing and Configuring SSM Agent on Linux Instances.

The Command document is the key

To install the Infrastructure agent, I’ll use the Systems Manager Run Command, which is an EC2 Systems Manager command that, according to the documentation, “lets you remotely and securely manage the configuration of your managed instances.” To execute a Run Command on SSM agents installed in your EC2 infrastructure, you use a Command document.

Command documents are JSON-formatted files that contain the necessary parameters and options to execute a command on an SSM agent. Systems Manager contains existing documents that you can customize for your own needs, but in this case I’ll use a Command document for installing the Infrastructure agent that I wrote, called New-Relic_Infrastructure. (I’ve already added this document to all available AWS regions—it’s available for anyone to load and use, or you could fork it from GitHub.)

You use this Command document to configure parameters in the Infrastructure agent’s configuration file (newrelic-infra.yml). As you’ll see in the following steps, Systems Manager reads New-Relic_Infrastructure and creates a form for you to fill out when you install the agent.

There are only two required options that must be set: Action and License Key. The default Action is Install, and the value for License Key must be your New Relic license key, which is required to perform any action on the Infrastructure agent with the Run Command.

For example, here’s an excerpt of New-Relic_Infrastructure that shows that two required settings:










            "description":"(Required) Install, update, or remove. Note: update only updates the Infrastructure agent, it doesn't update or change the agent configuration.",











            "description":"(Required) Your New Relic license key.",




(Note: This post focuses on using the Command document to install the Infrastructure agent, but you can also use this command document to update or remove the agent. A license key is required for security even if you’re just removing or updating the agent.)

The rest of the configuration parameters are optional and are documented in the Infrastructure agent configuration docs.

And, as I’ve mentioned, this command document is cross platform and can install Infrastructure agents on supported Linux and Windows instances at the same time.

Let’s do it—install the Infrastructure agent using the Run Command

Now let’s walk through the steps to install the Infrastructure agent with EC2 Systems Manager. (Note: You can execute a Run Command in only one region at a time.)

  1. Log in to your Amazon EC2 Dashboard.
  2. Navigate to the Systems Manager Services section, and select Run Command.
  3. Use the document requester drop-down (defaults to Owned by Me or Amazon) and change it to Public Documents.
  4. Click in the search field to bring up the Resource Attributes filter and select Name.

    document selector

  5. Type “New-Relic_Infrastructure” and click Enter. You’ll see the the New-Relic_Infrastructure document listed.

    command document selected

    After you select the New-Relic_Infrastructure Command document, you’ll see all of the fields available for you to fill out. Required fields are noted with an asterisk; any others are optional.

  6. Select the instance or instances on which you want to run New-Relic_Infrastructure command document. Select instances manually or by specifying a tag. Note: You can select only instances for the region you are currently working in. You can select multiple instances with different operation systems as long as the Infrastructure agent supports those operating systems.
  7. Select the Action (in this case, Install) and add your New Relic license key.

    set action and licenseThe rest of the fields are optional and are used to configure the agent configuration file or add custom attributes. Follow the Infrastructure agent configuration documentation to set these as needed. The Comment field is a standard SSM field; I recommend entering something that describes the instances you’ve selected to run the Command on, should you need to reference this later.

  8. When you’ve completed all the fields you need, click Run.

Reviewing the agent installation output

The following dialog gives you the option to view the agent installation output by clicking the Command ID link (which takes you directly to the details for that specific command) or View result (which leads to a list of all command run results).

command run success

Here, I’ve clicked the Command ID link:

command id link


To view the Run Command’s output, select the Output tab.output_tab
Since the Command document handled the Infrastructure agent installation on both Linux and Windows instances, you can see the entries for each. To view the output for either installations, click View Output.

And we’re done here!

That’s it—we’re finished: the New Relic Infrastructure agent has been installed on the selected instances and data will start streaming to your New Relic console shortly. Now you can see the metrics and data that the Infrastructure agent captures. You’ll also be able to see all of the integration attributes of your EC2 instance. You can use these attributes to filter how you view your infrastructure monitoring and even create filter sets to better organize your hosts.

Deploying the New Relic Infrastructure agent doesn’t get much easier than this.

Attending AWS re:Invent?

Going to be in Las Vegas for AWS re:Invent 2017? So are we! Be sure to drop by and see us at Booth #2412, and don’t miss these informative New Relic breakout sessions: