文档 Grafana 文档 警报 附加配置 供应警报资源 使用 Terraform 进行供应

使用 Terraform 供应警报资源

使用 Terraform 的 Grafana Provider 管理你的警报资源并将其配置到 Grafana 系统中。对 Grafana 警报的 Terraform provider 支持使得以代码形式轻松创建、管理和维护你的整个 Grafana 警报栈成为可能。

本指南概述了使用 Terraform 供应警报资源的步骤和参考。对于实际演示，你可以克隆并尝试这个使用 Grafana OSS 和 Docker Compose 的示例。

要使用 Terraform 创建和管理你的警报资源，你需要完成以下任务。

1. 创建一个 API 密钥来配置 Terraform provider。
2. 通过以下方式以 Terraform 格式创建你的警报资源：
   • 导出已配置的警报资源
   • 或编写 Terraform 警报 schema。

     默认情况下，你无法在 Grafana 中编辑通过 Terraform 供应的资源。在 Terraform 资源中启用 disable_provenance 属性以允许在 Grafana UI 中进行更改。

3. 运行 terraform apply 命令来供应你的警报资源。

开始之前，你需要在你的机器上安装 Grafana 实例和 Terraform。

创建 API 密钥并配置 Terraform provider

你可以创建一个服务账户令牌来认证 Terraform 与 Grafana。要为供应警报资源创建 API 密钥，请完成以下步骤。

1. 创建一个新的服务账户。
2. 分配角色或权限以访问警报供应 API。
3. 创建一个新的服务账户令牌。
4. 命名并保存令牌以便在 Terraform 中使用。

现在你可以进入你的 Terraform 配置工作目录，并创建一个名为 main.tf 的文件，如下所示：

main.tf 复制

terraform {
    required_providers {
        grafana = {
            source = "grafana/grafana"
            version = ">= 2.9.0"
        }
    }
}

provider "grafana" {
    url = <grafana-url>
    auth = <api-key>
}

替换以下值：

• 将 <grafana-url> 替换为 Grafana 实例的 URL。
• 将 <api-key> 替换为之前创建的 API 令牌。

此 Terraform 配置安装 Grafana Terraform provider 并使用 API 令牌针对你的 Grafana 实例进行认证。对于包括基本认证在内的其他认证方式，请参考 auth 选项文档。

对于 Grafana Cloud，请参考使用 Terraform 管理 Grafana Cloud Stack 的说明。对于基于角色的访问控制，请参考使用 Terraform 供应 RBAC 和警报供应角色（fixed:alerting.provisioning.*）。

为警报资源创建 Terraform 配置

Grafana Terraform provider 使你能够管理以下警报资源。

在本节中，我们将为每个警报资源创建 Terraform 配置，并演示如何将它们相互关联。

添加警报规则

警报规则使你能够通过查询任何后端 Grafana 数据源来接收警报。

1. 首先，创建一个要查询的数据源和一个用于存储规则的文件夹。

   在本示例中，使用了 TestData 数据源。

   terraform 复制

   resource "grafana_data_source" "<terraform_data_source_name>" {
       name = "TestData"
       type = "testdata"
   }
   
   resource "grafana_folder" "<terraform_folder_name>" {
       title = "My Rule Folder"
   }

   替换以下字段值：

   • 将 <terraform_data_source_name> 替换为数据源的 terraform 名称。
   • 将 <terraform_folder_name> 替换为文件夹的 terraform 名称。

2. 在 Grafana 中创建或找到你要导入的警报规则。

3. 以 Terraform 格式导出警报规则组。这会将警报规则组导出为 grafana_rule_group Terraform 资源。

   你可以编辑导出的资源，或者考虑从头创建资源。

   terraform 复制

   resource "grafana_rule_group" "<terraform_rule_group_name>" {
       name = "My Alert Rules"
       folder_uid = grafana_folder.<terraform_folder_name>.uid
       interval_seconds = 60
       org_id = 1
   
       rule {
           name = "My Random Walk Alert"
           condition = "C"
           for = "0s"
   
           // Query the datasource.
           data {
               ref_id = "A"
               relative_time_range {
                   from = 600
                   to = 0
               }
               datasource_uid = grafana_data_source.<terraform_data_source_name>.uid
               // `model` is a JSON blob that sends datasource-specific data.
               // It's different for every datasource. The alert's query is defined here.
               model = jsonencode({
                   intervalMs = 1000
                   maxDataPoints = 43200
                   refId = "A"
               })
           }
   
           // The query was configured to obtain data from the last 60 seconds. Let's alert on the average value of that series using a Reduce stage.
           data {
               datasource_uid = "__expr__"
               // You can also create a rule in the UI, then GET that rule to obtain the JSON.
               // This can be helpful when using more complex reduce expressions.
               model = <<EOT
   {"conditions":[{"evaluator":{"params":[0,0],"type":"gt"},"operator":{"type":"and"},"query":{"params":["A"]},"reducer":{"params":[],"type":"last"},"type":"avg"}],"datasource":{"name":"Expression","type":"__expr__","uid":"__expr__"},"expression":"A","hide":false,"intervalMs":1000,"maxDataPoints":43200,"reducer":"last","refId":"B","type":"reduce"}
   EOT
               ref_id = "B"
               relative_time_range {
                   from = 0
                   to = 0
               }
           }
   
           // Now, let's use a math expression as our threshold.
           // We want to alert when the value of stage "B" above exceeds 70.
           data {
               datasource_uid = "__expr__"
               ref_id = "C"
               relative_time_range {
                   from = 0
                   to = 0
               }
               model = jsonencode({
                   expression = "$B > 70"
                   type = "math"
                   refId = "C"
               })
           }
       }
   }

   替换以下字段值：

   • 将 <terraform_rule_group_name> 替换为警报规则组的名称。

   请注意，不同的 Grafana 资源通过其 Terraform 配置中的 uid 值相互连接。uid 值在供应时将随机生成。

   在此示例中，要将警报规则组与其对应的数据源和文件夹关联起来，请替换以下字段值：

   • 将 <terraform_data_source_name> 替换为之前定义的数据源的 terraform 名称。
   • 将 <terraform_folder_name> 替换为之前定义的文件夹的 terraform 名称。

4. 继续添加更多 Grafana 资源或使用 Terraform CLI 进行供应。

添加联系点

联系点是警报通知的接收者。

1. 在 Grafana 中创建或找到你要导入的联系点。或者，考虑像下面示例中所示那样用代码编写资源。

2. 以 Terraform 格式导出联系点。这会将联系点导出为 grafana_contact_point Terraform 资源——如有必要，可进行编辑。

3. 在本示例中，警报通知在周末被静默。

   terraform 复制

    resource "grafana_contact_point" "<terraform_contact_point_name>" {
        name = "My contact point email"
   
        email {
            addresses               = ["<email_address>"]
        }
    }

   替换以下字段值：

   • 将 <terraform_contact_point_name> 替换为联系点的 terraform 名称。该名称将用于在其他 Terraform 资源中引用此联系点。
   • 将 <email_address> 替换为接收警报通知的电子邮件地址。

4. 继续添加更多 Grafana 资源或使用 Terraform CLI 进行供应。

添加并启用通知模板

通知模板允许跨多个联系点自定义警报通知。

1. 在 Grafana 中创建或找到你要导入的通知模板组。或者，考虑像下面示例中所示那样用代码编写资源。

2. 将通知模板组导出为 grafana_message_template Terraform 资源。

   此示例创建了一个名为 custom_emails 的通知模板组，该组定义了一个 custom_email.message 模板。

   terraform 复制

    resource "grafana_message_template" "<terraform_message_template_name>" {
        name = "custom_emails"
   
        template = <<EOT
    {{ define "custom_email.message" }}
    Lorem ipsum - Custom alert!
    {{ end }}
    EOT
    }

   这使得联系点可以使用通知模板组内的通知模板（{{ define "<NAME>"}}）。

3. 在之前的联系点中，通过如下设置 email.message 属性来启用模板。

   terraform 复制

    resource "grafana_contact_point" "<terraform_contact_point_name>" {
        name = "My contact point email"
   
        email {
            addresses               = ["<email_address>"]
            message                 = "{{ template \"custom_email.message\" .}}"
        }
    }

4. 继续添加更多 Grafana 资源或使用 Terraform CLI 进行供应。

添加静默时间

静默时间会在预定的时间间隔内暂停警报通知。

1. 在 Grafana 中创建或找到你要导入的静默时间。或者，考虑像下面示例中所示那样用代码编写资源。

2. 以 Terraform 格式导出静默时间。这会将静默时间导出为 grafana_mute_timing Terraform 资源——如有必要，可进行编辑。

3. 此示例在周末关闭通知。

   terraform 复制

    resource "grafana_mute_timing" "<terraform_mute_timing_name>" {
        name = "No weekends"
   
        intervals {
            weekdays = ["saturday", "sunday"]
        }
    }

   替换以下字段值：

   • 将 <terraform_mute_timing_name> 替换为 Terraform 资源的名称。该名称将用于在 Terraform 通知策略树中引用此静默时间。

4. 继续添加更多 Grafana 资源或使用 Terraform CLI 进行供应。

添加通知策略树

通知策略定义了如何将警报实例路由到你的联系点。

1. 找到默认通知策略树。或者，考虑像下面示例中所示那样用代码编写资源。

2. 以 Terraform 格式导出通知策略树。这会将其导出为 grafana_notification_policy Terraform 资源——如有必要，可进行编辑。

   terraform 复制

   resource "grafana_notification_policy" "my_policy_tree" {
   contact_point = grafana_contact_point.<terraform_contact_point_name>.name
   ...
   
   policy {
       contact_point = grafana_contact_point.<terraform_contact_point_name>.name
   
       matcher {...}
   
       mute_timings = [grafana_mute_timing.<terraform_mute_timing_name>.name]
   }
   }

   要在通知策略树中配置之前创建的静默时间和联系点，请替换以下字段值：

   • 将 <terraform_data_source_name> 替换为之前定义的联系点的 terraform 名称。
   • 将 <terraform_folder_name> 替换为之前定义的静默时间的 terraform 名称。

3. 继续添加更多 Grafana 资源或使用 Terraform CLI 进行供应。

在 Grafana UI 中启用资源编辑

默认情况下，你无法在 Grafana 中编辑通过 Terraform 供应的资源。这确保你的警报栈始终与你的 Terraform 代码保持同步。

要使已供应的资源在 Grafana UI 中可编辑，请在警报资源上启用 disable_provenance 属性。

terraform 复制

resource "grafana_contact_point" "my_contact_point" {
  name = "My Contact Point"

  disable_provenance = true
}

resource "grafana_message_template" "custom_notification_template_group" {
  name     = "custom_notification_template_group"
  template = "{{define \"template1\" }}Say{{ end }}{{define \"template2\" }}Hi!{{ end }}"

  disable_provenance = true
}
...

使用 Terraform 供应 Grafana 资源

要使用 Terraform CLI 在 Grafana 中创建上述警报资源，请完成以下步骤。

1. 初始化包含 Terraform 配置文件的目录。

   shell 复制

   terraform init

   此命令初始化 Terraform 目录，安装 main.tf 文件中配置的 Grafana Terraform provider。

2. 应用 Terraform 配置文件来供应资源。

   shell 复制

   terraform apply

   在将任何更改应用到 Grafana 之前，Terraform 会显示执行计划并请求你的批准。

   shell 复制

    Plan: 4 to add, 0 to change, 0 to destroy.
   
    Do you want to perform these actions?
    Terraform will perform the actions described above.
    Only 'yes' will be accepted to approve.
   
    Enter a value:

   一旦你确认继续进行更改，Terraform 将在 Grafana 中创建已供应的资源！

   shell 复制

   Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

现在你可以访问 Grafana 来验证不同资源的创建。

更多示例

关于本指南概念的更多示例：

• 尝试使用 Terraform 和 Docker Compose 在 Grafana OSS 中供应警报资源的演示。
• 在 Grafana Terraform Provider 文档中查阅 Terraform 警报 schema 的所有可用选项和示例。
• 查阅使用 Terraform 管理 Grafana Cloud Stack 的教程。