Terraform is a popular infrastructure-as-code software tool built by HashiCorp. You use it to provision all kinds of infrastructure and services, including New Relic and alerts. New Relic has developed a Terraform provider to configure alerts, synthetics, dashboards, and other parts of New Relic through declarative configuration files. This approach lets you define alert policies, notification channels, dashboards, and synthetic monitors as code, so your observability configuration gets the same rigor as your infrastructure.
The New Relic Terraform provider automates the configuration of New Relic. With it you can provision an alert policy, four alert conditions, and a notification channel from a single plan. The four alert conditions align with the four golden signals of monitoring introduced in Google’s Site Reliability Engineering book:
- Latency: The amount of time it takes your application to service a request.
- Traffic: The amount of requests your system receives.
- Errors: The rate of requests that fail.
- Saturation: The stress on resources to meet the demands of your application.
Terraform is an open-source infrastructure as code software tool that provides a consistent CLI workflow to manage hundreds of cloud services. Terraform codifies cloud APIs into declarative configuration files.
Prerequisites and Account Setup
Before you begin to use this guide, you should have some basic knowledge of both New Relic and Terraform. If you haven't deployed a New Relic open source agent yet, install New Relic for your application. Also, install the Terraform CLI.
You need three things from your New Relic account:
- Account ID - Found in the URL when logged in or in Account Settings
- API Key - A User API key (not the License key or Insights key)
- Region - US, EU, or JP
Getting Your API Key
- Go to New Relic > API Keys (under your profile menu)
- Click "Create a key"
- Select "User" as the key type
- Give it a name like "Terraform Automation"
Set environment variables for convenience:
export NEW_RELIC_ACCOUNT_ID="1234567"
export NEW_RELIC_API_KEY="NRAK-your-api-key-here"
export NEW_RELIC_REGION="US" # or "EU" / "JP"
Most user keys begin with the prefix NRAK-.
Provider Installation and Version Management
New Relic offers tools that help you fix problems quickly, maintain complex systems, improve your code, and accelerate your digital transformation. With the New Relic Terraform provider you are able to automate the configuration of New Relic.
The provider supports Terraform 1.0+.
New Relic and the Terraform team will support Terraform versions up to 2 years after the latest release. We advice to always upgrade to the latest version of Terraform and the New Relic Terraform provider.
To use the latest version of the provider in your Terraform environment, run terraform init and Terraform will automatically install the provider.
If you wish to pin your environment to a specific release of the provider, you can do so with a required_providers statement in your Terraform manifest. The terraform configuration block varies slightly depending on which Terraform version you're using.
Version Pinning Table
| Element | Example Value | Purpose |
|---|---|---|
| required_version | ~> 1.0 | Require Terraform version 1.0 |
| provider source | newrelic/newrelic | Registry namespace |
| provider version | ~> 3.89 | Pin to major provider line |
| provider version 2.x | ~> 2.x | Latest 2.x version |
Bootstrap a Terraform Project for New Relic
Start by initializing a working directory and creating a Terraform configuration file:
$mkdir terraform-project && cd terraform-project
$touch main.tf
Next, instruct Terraform to install and use the New Relic provider, by setting the terraform and required_providers blocks in main.tf:
terraform {
required_version = "~> 1.0"
required_providers {
newrelic = {
source = "newrelic/newrelic"
}
}
}
In this code block, you're setting the required version of Terraform to 1.0 and setting the New Relic provider to the latest 2.x version. Using the right version constraints for your setup will provide better stability with your Terraform runs.
A versions file with an explicit pin can be used as well:
terraform {
required_providers {
newrelic = {
source = "newrelic/newrelic"
version = "~> 3.89"
}
}
}
Configuring the New Relic Provider
With terraform all set, configure the New Relic provider with the following items:
- Your New Relic account ID.
- Your New Relic API key. Most user keys begin with the prefix NRAK-.
- Your New Relic region
A basic provider configuration using variables:
provider "newrelic" {
account_id = var.new_relic_account_id
api_key = var.new_relic_api_key
region = var.new_relic_region
}
Variable definitions:
variable "new_relic_account_id" {
description = "New Relic account ID"
type = number
}
variable "new_relic_api_key" {
description = "New Relic User API key"
type = string
sensitive = true
}
variable "new_relic_region" {
description = "New Relic region (US, EU, or JP)"
type = string
default = "US"
}
Or using environment variables, the simplest approach:
provider "newrelic" {
# Reads from NEW_RELIC_ACCOUNT_ID, NEW_RELIC_API_KEY, and NEW_RELIC_REGION
}
Provider Capabilities and Use Cases
The Terraform New Relic provider lets you define alert policies, notification channels, dashboards, and synthetic monitors as code, so your observability configuration gets the same rigor as your infrastructure.
What does New Relic provide
New Relic has developed a Terraform provider to configure alerts, synthetics, dashboards, and other parts of New Relic through declarative configuration files.
How to get started
Follow the instructions on Terraform provider documentation: Getting Started with the New Relic Provider
Managing New Relic with Terraform is valuable when you need to deploy thousands of Synthetic Monitors. Options range from manual creation to a script via the New Relic REST API. Both examples focus on creating the resources, but do not address their future management. With the New Relic provider in Terraform you can move all things from New Relic to Terraform and keep it inside the repository.
Terraform is a powerful open-source tool for implementing Infrastructure as Code, widely used for managing cloud resources effectively. The tool is used mainly for cloud resources. Right now some of the companies recommend it as a default way to operate with their systems.
Golden Signals Mapping
| Signal | Terraform Resource Example | Metric Focus |
|---|---|---|
| Latency | newrelicalertcondition | Request duration |
| Traffic | newrelicalertcondition | Request throughput |
| Errors | newrelicalertcondition | Error rate |
| Saturation | newrelicalertcondition | Resource utilization |
Workflow Tips and IDE Integration
Simplify your workflow by bringing the Terraform documentation right into your IDE with New Relic's CodeStream IDE extension. Add templates for any New Relic resource type with just a click.
In this guide you will learn how to set up New Relic with Terraform, but you can review the New Relic Terraform provider documentation to learn how to set up other New Relic resources.
Operational Considerations
If you are not familiar with Terraform and would like to get basic knowledge then this video explains everything needed.
Installing Terraform
As mentioned at the beginning, we had to find a way not only deploy the objects in New Relic but also how to handle the operational things. Terraform provides a plan-apply-diff cycle that makes operational changes auditable and repeatable.
A comprehensive guide approach covers:
- Creating a deployment plan for deploying thousands of Synthetic Monitors
- Managing operational things after initial deployment
- Keeping observability configuration versioned alongside application code
Conclusion
Using Terraform with New Relic transforms observability from a manual console workflow into declarative, versioned, and repeatable infrastructure. The New Relic Terraform provider covers alerts, synthetics, dashboards, and notification channels, allowing teams to apply the same IaC discipline to monitoring as they do to cloud resources.
Provisioning starts with correct account credentials: Account ID, User API key beginning with NRAK-, and region selection US, EU, or JP. Provider installation is handled via required_providers with source newrelic/newrelic and version constraints, and initialization via terraform init. Configuration can be expressed with variables or environment variables, and supports pinning for stability.
The four golden signals of Latency, Traffic, Errors, and Saturation provide a consistent foundation for alert conditions tied to an alert policy and notification channel. Combined with IDE integration through CodeStream and support for Terraform 1.0+ with two-year version support windows, the provider enables teams to scale observability configuration safely, review changes via plan, and maintain state in a repository for long-term management.