From a4adc8e5c61542a14b733b526b342888c3996abd Mon Sep 17 00:00:00 2001 From: mmfred Date: Wed, 13 May 2020 07:46:36 -0700 Subject: [PATCH 001/526] Create guide_template.markdown basic template to get started on guides. This is just for writing and there are some open questions - I'm sure there are some style changes needed to work with the js guide. I'm not sure how we are doing videos, for example. --- src/markdown-pages/guide_template.markdown | 33 ++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 src/markdown-pages/guide_template.markdown diff --git a/src/markdown-pages/guide_template.markdown b/src/markdown-pages/guide_template.markdown new file mode 100644 index 000000000..00e919204 --- /dev/null +++ b/src/markdown-pages/guide_template.markdown @@ -0,0 +1,33 @@ +Use this template to create guides. Make a copy, rename the document, and add your guide content. Add or remove sections, as appropriate. + + +## + +Write an intro paragraph that engages the user, tells them what they'll learn, and what problems they'll solve. + +ADD VIDEO/SCREENSHOT/GIF + +### Before you begin + +Add a list of prerequisites. For example: +- Create a developer account +- Get an API key +- Download the New Relic One CLI + +1. Write the step info. Does not have to be long and verbose. + +``` +Add code example +``` +2. Write the step info. Repeat as many times as needed. Increment up the step number. + +``` +Add code example +``` + +Related info + +- Link to next logical guide +- Link to related content like reference docs +- Link to related opensource.newrelic.com, docs.newrelic.com, blog, git docs, or other related content. + From e7d5bd02ec759a18d19f3d582b9cd8224efa08ab Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 3 Jun 2020 11:35:40 +0200 Subject: [PATCH 002/526] First commit --- src/markdown-pages/get-started-terraform.mdx | 235 +++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 src/markdown-pages/get-started-terraform.mdx diff --git a/src/markdown-pages/get-started-terraform.mdx b/src/markdown-pages/get-started-terraform.mdx new file mode 100644 index 000000000..559036d70 --- /dev/null +++ b/src/markdown-pages/get-started-terraform.mdx @@ -0,0 +1,235 @@ +--- +path: '/guides/get-started-terraform' +duration: '20 min' +title: 'Use New Relic with Terraform' +template: 'GuideTemplate' +description: '' +--- + +Intro + +## Before You Begin + +* This guide assumes you already have a New Relic agent deployed. If you don't have New Relic integrated yet, check out [New Relic's introduction documentation](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/get-started/introduction-new-relic) to get started there, then head back over here to get started with the New Relic Terraform Provider. +* [Install Terraform](https://www.terraform.io/intro/getting-started/install.html) +and read the Terraform getting started guide that follows. This guide will +assume a basic understanding of Terraform. +* Locate your Admin's API key by following [New Relic's Admin API key docs](https://docs.newrelic.com/docs/apis/get-started/intro-apis/types-new-relic-api-keys#admin). + +## First things first: Credentials + +The environment variable `NEWRELIC_API_KEY` is automatically detected by the New Relic Terraform Provider when running `terraform` commands, so we recommend adding this environment variable to your machine's startup file, such as your `.bash_profile`. + +This guide assumes your API key has been set with an environment variable. + +-> You can set the environment variable `NEWRELIC_API_KEY` in your `.bash_profile` or `.bashrc` file (on UNIX machines). Or you can set the variable inline with the `terraform plan` or `terraform apply` commands (see examples below). + +**.bash_profile** + +```bash +# Add this to your .bash_profile +export NEWRELIC_API_KEY=abc123 +``` + +Example inline with `terraform` command + +```bash +$ NEWRELIC_API_KEY=abc123 terraform apply +``` + +## Configuring the Provider + +Let's start with a minimal Terraform config file to create an Alert Policy. + +**main.tf** + +```hcl +provider "newrelic" {} + +resource "newrelic_alert_policy" "alert_policy_name" { + name = "My Alert Policy Name" +} +``` +We'll add an Alert Condition under this policy as we move through this guide. + + +## Initialize Your Terraform Setup + +At this point you should be able to initialize your Terraform setup, so let's give it a try. + +```bash +$ terraform init +``` + +-> This is the first command that should be run for any new or existing Terraform configuration per machine. This sets up all the local data necessary to run Terraform that is typically not committed to version control. This command is always safe to run multiple times. + +Once you've successfully initialized your Terraform working directory, try running the following command. + +```bash +$ terraform plan +``` + +This command will output some information into your console regarding Terraform's execution plan. Running `terraform plan` is essentially a "dry run" and will not provision anything. We'll get to provisioning in the next steps. + +## Add an Alert Condition to an Alert Policy + +We started with a minimal configuration with an Alert Policy, but it doesn't contain any Alert Conditions. Let's add an Alert Condition to that policy which we'll associate the condition to an application. + +First, let's add a data source by adding a `data` block. This will store your application's information for Terraform to use. + +```hcl +provider "newrelic" {} + +# Data Source +data "newrelic_application" "app_name" { + name = "my-app" # Note: This must be an exact match of your app name in New Relic (Case sensitive) +} + +resource "newrelic_alert_policy" "alert_policy_name" { + name = "My Alert Policy Name" +} +``` + +-> Terraform's data sources are read-only views into pre-existing data, or they compute new values on the fly within Terraform itself. More information on data sources can be found [here](https://www.terraform.io/docs/configuration-0-11/data-sources.html). + + +Now let's add the Alert Condition so we can see an alert when a particular scenario occurs. + +```hcl +provider "newrelic" {} + +data "newrelic_application" "app_name" { + name = "my-app" +} + +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_application.app_name.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" + } +} +``` + +This alert condition will be triggered when the [Apdex score](https://docs.newrelic.com/docs/apm/new-relic-apm/apdex/apdex-measure-user-satisfaction) of your application falls below the threshold of `0.75` for 5 minutes. This alert is considered `critical` in priority based on the configuration. + +But how will you actually be alerted if this scenario occurs? To control where to send alerts, we'll need to configure a Notification Channel for the alert. + +## Add a Notification Channel + +New Relic alerts are great, but they're even better when combined with good notifications. To wire up a notification to your previously configured Alert Condition and Alert Policy, add the following to your configuration file. + +```hcl +# Notification channel +resource "newrelic_alert_channel" "alert_notification_email" { + name = "paul@example.com" + type = "email" + + config { + recipients = "paul@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 = [ + newrelic_alert_channel.alert_notification_email.id + ] +} +``` + +This example will send an email to the specified recipients whenever the associated alert condition is triggered. If you would like to send notifications via different modalities, such as Slack, you can configure updating the `type` in your [alert channel](https://www.terraform.io/docs/providers/newrelic/r/alert_channel.html). + +## A Note About Secrets + +As part of a `newrelic` resource, there is often some amount of configuration +that is required in order for a resource to reach its full potential. In some +cases, once a given entity is created, API results will obscure the values for +items that are deemed to be secret. As a result, Terraform is unable to make +an accurate detection of a resource state, and so marks a resource as changed +for every run. + +Consider the following example. + +```hcl +resource "newrelic_alert_channel" "slack" { + name = "slack" + type = "slack" + + config { + channel = "test" + url = "https://hooks.slack.com/services/xxxx/xxxxx" + } +} +``` + +The resource above yields the following plan. + + -/+ newrelic_alert_channel.slack (new resource required) + id: "2344397" => (forces new resource) + config.%: "1" => "2" (forces new resource) + config.channel: => (attribute changed) + config.url: => (forces new resource) + name: "slack" => "slack" + type: "slack" => "slack" + +To avoid the resource being marked as changed every run, the following can be +implemented for the resource. + +```hcl +resource "newrelic_alert_channel" "slack" { + ... + lifecycle { + ignore_changes = ["config"] + } +} + ... +``` + +This should avoid any of the configuration items from causing a change to the +resource. + + + +## Apply Your Terraform Configuration + +To summarize, so far we've configured an Alert Policy that contains an Alert Condition that is associated with a specific application, but we haven't actually provisioned these resources in our New Relic account. Let's do that now. + +To apply your configuration and provision these resources in your New Relic account, run the following command. + +```bash +$ terraform apply +``` + +Follow the prompt, which should involve you answering `yes` to apply the changes. Terraform will then provision the resources. + +Once complete, you'll be able to navigate to your Alerts tab in your New Relic account and click on Alert Policies. You should see your newly created alert policy. Clicking on the alert policy should display the associated alert condition that we just configured as well. + +If you ever need to make changes to your configuration, you can run `terraform apply` again after saving your latest configuration and Terraform will update the proper resources with your changes. + +You can also run `terraform destroy` to tear down your resources if that's ever needed. + + + +### Related info + +- [New Relic documentation](https://docs.newrelic.com) +- [Community page for how to add a time picker](https://discuss.newrelic.com/t/how-to-add-the-time-picker-to-nrql-queries/94268) From 58bd6b86318696782fdc0b84f5c1107ab22f450b Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Wed, 3 Jun 2020 14:45:00 +0200 Subject: [PATCH 003/526] Ready for review --- src/markdown-pages/get-started-terraform.mdx | 182 +++++++++++-------- 1 file changed, 104 insertions(+), 78 deletions(-) diff --git a/src/markdown-pages/get-started-terraform.mdx b/src/markdown-pages/get-started-terraform.mdx index 559036d70..36c69f19d 100644 --- a/src/markdown-pages/get-started-terraform.mdx +++ b/src/markdown-pages/get-started-terraform.mdx @@ -3,45 +3,40 @@ path: '/guides/get-started-terraform' duration: '20 min' title: 'Use New Relic with Terraform' template: 'GuideTemplate' -description: '' +description: "Learn how to set up New Relic with [Terraform](https://www.terraform.io/) and create alerts with notifications." --- -Intro +In this guide you'll learn how to set up New Relic for the first time with [Terraform](https://www.terraform.io/). Specifically, you are going to provision an alert policy with notifications in your New Relic account using Terraform. -## Before You Begin +