• Sign up

Set up New Relic using Terraform

20 min

Terraform is a popular infrastructure as code software tool by HashiCorp. You can use it to provision all kind of infrastructure and services, including New Relic entities.

In this guide you'll learn how to set up New Relic for the first time with Terraform. More specifically, you are going to provision an alert policy with notifications in your New Relic account using Terraform.

Before you begin

To use this guide, you should have some basic knowledge of both New Relic and Terraform.

Step 1 of 8

Bootstrap your provider configuration

Our Terraform Provider detects the environment variables above when running Terraform commands.

You can set the environment variables in your .bash_profile or .bashrc file.

Set the following environment variables:

  • Set your New Relic Personal API key with the NEW_RELIC_API_KEY environment variable. Most Personal API keys begin with the prefix NRAK-.
  • Set your New Relic Admin API key with the NEW_RELIC_ADMIN_API_KEY environment variable. Most Admin API keys begin with the prefix NRAA-.
  • Set your New Relic Account ID with the NEW_RELIC_ACCOUNT_ID environment variable.
  • Set your New Relic region with the NEW_RELIC_REGION environment variable. Your region is US if your account settings page is located at rpm.newrelic.com, and EU if your account is located at rpm.eu.newrelic.com.
# Add this to your .bash_profile
# Or set it inline when running `terraform plan` or `terraform apply`:
$ NEW_RELIC_API_KEY=NRAK-... terraform apply

Step 2 of 8

Start with a provider configuration

To connect Terraform with New Relic, you need to set New Relic as a provider in your Terraform configuration file, so that Terraform can create and manage New Relic resources in your account.

To set New Relic as a provider, create a Terraform configuration file (main.tf). This code sets newrelic as the Terraform provider and provisions an empty alert policy as the resource.

provider "newrelic" {}
resource "newrelic_alert_policy" "alert_policy_name" {
name = "My Alert Policy Name"

Step 3 of 8

Initialize and test your setup

After adding New Relic as a provider, initialize the working directory from the command line using terraform init.

Once you've successfully initialized the working directory, test Terraform's execution plan using terraform plan to confirm that you've the right setup.

# Initialize the working directory
$ terraform init
# Test the Terraform plan
$ terraform plan

plan performs a dry run of your Terraform configuration, so nothing is actually provisioned. Always run plan to test your configuration before applying it.

Step 4 of 8

Add a data source

The alert policy you defined in main.tf does not contain any alert condition. You are going to add an alert condition linked to your application.

To store your application's information, you need to add a data source.

provider "newrelic" {}
# Data Source
data "newrelic_entity" "app_name" {
name = "my-app" # This must be an exact match of your app name in New Relic (case sensitive)
domain = "APM"
resource "newrelic_alert_policy" "alert_policy_name" {
name = "My Alert Policy Name"

Step 5 of 8

Add an alert condition to the alert policy

Now you can add the alert condition. For example, you can create a critical alert condition that is triggered when the Apdex of your application falls below 0.75 for five minutes.

provider "newrelic" {}
data "newrelic_entity" "app_name" {
name = "my-app"
domain = "APM"
resource "newrelic_alert_policy" "alert_policy_name" {
name = "My Alert Policy Name"
# Alert condition
resource "newrelic_alert_condition" "alert_condition_name" {
policy_id = newrelic_alert_policy.alert_policy_name.id
name = "My Alert Condition Name"
type = "apm_app_metric"
entities = [data.newrelic_entity.app_name.application_id]
metric = "apdex"
runbook_url = "https://www.example.com"
condition_scope = "application"
term {
duration = 5
operator = "below"
priority = "critical"
threshold = "0.75"
time_function = "all"

Step 6 of 8

Add a notification channel

Alert policies use notification channels to inform you about incidents and active alerts. To add a notification channel to your alert policy, add the following snippet to your configuration file.

When the alert condition is triggered, the notification channel sends an email to the specified recipients. You can send notifications using different tools and channels, such as Slack, by changing the type of your alert channel.

# Notification channel
resource "newrelic_alert_channel" "alert_notification_email" {
name = "paul@example.com"
type = "email"
config {
recipients = "fab@example.com"
include_json_attachment = "1"
# Link the above notification channel to your policy
resource "newrelic_alert_policy_channel" "alert_policy_email" {
policy_id = newrelic_alert_policy.alert_policy_name.id
channel_ids = [

Step 7 of 8

Apply your Terraform configuration

The last step is provisioning the resources you've configured in main.tf, so that the alert policy is enabled in your New Relic account for your application.

To apply the Terraform configuration and provision the resources in your New Relic account, run terraform apply.

Answer yes when prompted to apply the changes. Once the apply process is complete, you should see the new alert policy you've provisioned using Terraform, and its alert conditions, in your New Relic account.

You can run terraform apply every time you need to make changes to your configuration. To eliminate the resources you've provisioned, run terraform destroy.

Step 8 of 8

Optional: Use the apm module for faster configuration

In the Terraform Registry you can find our apm module, which simplifies Terraform's configuration. apm creates an alert policy, a Synthetics monitor, and several alert conditions for a given application reporting data into New Relic.

To use our apm module with Terraform:

  1. Set newrelic/apm/newrelic as the module source.
  2. Add your account_id and application_name.
  3. Define your application_url (if any).

Here is a configuration example with overridden default values. Initialize the working directory using terraform initto download and enable the module.


The apm module doesn't create a notification channel, so you would still have to define one.

data "newrelic_alert_channel" "pager" {
name = "Page Developer Toolkit Team"
module "dummy-app-monitor" {
source = "newrelic/apm/newrelic"
account_id = 2520528
application_name = "Dummy App"
# An Apdex alert condition will be created with sensible defaults without the use of these attributes.
apdex_warning_threshold = 0.9
apdex_critical_threshold = 0.8
# An error rate alert condition will be created with sensible defaults without the use of these attributes.
error_rate_warning_threshold = 5
error_rate_critical_threshold = 10
# Specifying an application URL will provision a Synthetic monitor and associated alert condition.
application_url = "https://www.dummyapp.com"
synthetics_monitor_verify_ssl = true
# Response time alert condition will not be provisioned unless a critical violation threshold is specified.
response_time_critical_threshold = 3
channel_ids = [data.newrelic_alert_channel.pager.id]

Tip: Avoid resources being marked as "sensitive"

When API results are deemed to be secret and are obfuscated, Terraform may be unable to detect the state of a resource, marking it as changed. Consider this example:

resource "newrelic_alert_channel" "slack" {
name = "slack"
type = "slack"
config {
channel = "test"
url = "https://hooks.slack.com/services/xxxx/xxxxx"

Running terraform plan yields the following:

-/+ newrelic_alert_channel.slack (new resource required)
id: "2344397" => <computed> (forces new resource)
config.%: "1" => "2" (forces new resource)
config.channel: <sensitive> => <sensitive> (attribute changed)
config.url: <sensitive> => <sensitive> (forces new resource)
name: "slack" => "slack"
type: "slack" => "slack"

To prevent Terraform from wrongly marking a resource as changed, add an ignore_changes directive:

resource "newrelic_alert_channel" "slack" {
lifecycle {
ignore_changes = ["config"]

This avoids changes to resources caused by obfuscated items.