AWS CloudFormation integration

New Relic’s AWS CloudFormation integration allows you to add alert conditions to new or existing CloudFormation stacks using the New Relic Alerts resource provider. This document explains how to activate and use this integration.

Features

AWS CloudFormation is an Amazon Web Services (AWS) service that allows you to use programming languages or a simple text file to model and provision, in an automated and secure manner, all the resources needed for your applications across all regions and accounts. It allows you to simply create and duplicate a collection of AWS resources, known as a stack. Whenever a stack is generated, AWS CloudFormation provisions the resources that are specified in your template.

Using the CloudFormation integration for New Relic, you can add alert conditions to your CloudFormation template using our custom resource provider, giving you the ability to monitor your infrastructure and applications with New Relic Alerts.

Requirements

To use the Amazon CloudFormation integration, ensure your system meets these requirements:

• AWS Command Line Interface (AWS CLI) installed.
• New Relic REST API key.
• Optional: CloudFormation CLI installed.

Install the CloudFormation integration

To install the CloudFormation integration:

1. Navigate to the New Relic CloudFormation Partner Integration GitHub repository.
2. From the repository page, clone or download the repository.

Register the resource provider

To use private resource providers you must first register them with CloudFormation, in the accounts and regions in which you want to use them. Once you're registered a resource provider, it will appear in the CloudFormation registry for that account and region, and you can use it in your stack templates.

You can register the resource provider using one of the following methods:

Register using the CloudFormation API

To register the resource provider using the CloudFormation API:

1. In your terminal or command-line interface, run the RegisterType action to validate, package, and upload the resource provider to the CloudFormation Registry:

   aws cloudformation register-type --type-name NewRelic::Alerts::NrqlAlert --schema-handler-package s3://nr-cloudformation-downloads/newrelic-alerts-nrqlalert.zip --type RESOURCE

Note: If you are updating a previously registered resource, you can use the returned registration token to track the progress of the registration request using the DescribeTypeRegistration action in the CloudFormation API.

Token example:

Registration in progress with token: <3c27b9e6-dca4-4892-ba4e-3c0example>

Register using the CloudFormation CLI

To register the resource provider using the CloudFormation Command Line Interface (CLI):

1. Refer to the AWS CloudFormation Github README for instructions on downloading and installing the CloudFormation CLI.
2. Once you have installed the CloudFormation CLI, run the following command to validate, package, and upload the resource provider to the CloudFormation Registry:

   cfn submit -v --region <region>

Note: If you are updating a previously registered resource, you can use the returned registration token to track the progress of the registration request using the DescribeTypeRegistration action in the CloudFormation API.

Token example:

Validating your resource specification...
Packaging Java project
Creating managed upload infrastructure stack
Managed upload infrastructure stack already exists. Attempting to update
Managed upload infrastructure stack is up to date
Registration in progress with token: <3c27b9e6-dca4-4892-ba4e-3c0example>

Configure the resource provider

Once you have registered the resource, add the NewRelic::Alerts::NrqlAlert resource to the JSON or YAML file for your CloudFormation stack, using the following properties to configure the alert condition. For an example configuration, see the Lambda CloudFormation resource examples.

Example configuration

Lambda CloudFormation resource examples:

JSON example configuration

{
"AWSTemplateFormatVersion": "2010-09-09",
"Resources": {
    "LambdaNodeAlert": {
      "Type": "NewRelic::Alerts::NrqlAlert",
      "Properties": {
        "ApiKey": "YOUR_API_KEY",
        "PolicyId": YOUR_POLICY_ID,
        "NrqlCondition": {
          "Name": "Alert Condition NAme",
          "RunbookUrl": "http://example.com/runbook.html",
          "Enabled": false,
          "ExpectedGroups": 1,
          "IgnoreOverlap": true,
          "Terms": [
            {
              "Duration": 1,
              "Operator": "equal",
              "Priority": "critical",
              "Threshold": 1.0,
              "TimeFunction": "all"
            }
          ],
          "Nrql": {
            "Query": "SELECT count(*) FROM AwsLambdaInvocationError FACET provider.functionName",
            "SinceValue": 1
          }
        }
      }
    }
}

YAML example configuration

AWSTemplateFormatVersion: 2010-09-09
Resources:
  # Here's our custom resource type, which creates an alert in New Relic that triggers when the function is invoked
  LambdaNodeAlert:
    Type: NewRelic::Alerts::NrqlAlert
    Properties:
      #TODO: Your values here
      ApiKey: YOUR_API_KEY
      PolicyId: YOUR_POLICY_ID
      NrqlCondition:
        Name: Alert Condition Test
        RunbookUrl: http://example.com/runbook
        Enabled: true
        ExpectedGroups: 1
        IgnoreOverlap: true
        Terms:
          - Duration: 1
            Operator: "equal"
            Priority: "critical"
            Threshold: 1.0
            TimeFunction: "all"
        Nrql:
          Query: "SELECT count(*) FROM AwsLambdaInvocationError FACET provider.functionName"
          SinceValue: 1

Provision the Resource in a CloudFormation Stack

To use the resource provider to provision your stack and create an alert condition:

1. Once you have added the resource provider to your CloudFormation template, run the following command in your terminal or command-line interface to provision the resource and create your CloudFormation stack:

   aws cloudformation create-stack --region us-west-2 \
   --template-body "file://stack.yaml" \
   --stack-name NewRelicAlert
   

2. To view your alert, go to alerts.newrelic.com, select Alert policies > (selected policy) > Alert conditions.

What's next?

To learn more about using Alerts:

• Check out the New Relic University tutorial Intro to alert policies. Or, go directly to the full online course New Relic Alerting.
• Read Alerts best practices.
• Learn about the New Relic Alerts API.

For more help