Документация

Grafana

Документация GlaberGraph

Оповещения

Дополнительная конфигурация

Провижининг ресурсов Alerting

Провижининг с помощью Terraform

Use Terraform to provision alerting resources

Используйте Grafana Provider для Terraform, чтобы управлять вашими ресурсами оповещений и провижинить их в вашу систему Grafana. Поддержка Grafana Alerting в Terraform-провайдере упрощает создание, управление и поддержку всего вашего стека Grafana Alerting как кода.

Это руководство описывает шаги и ссылки для провижининга ресурсов оповещений с помощью Terraform. Для практической демонстрации вы можете клонировать и попробовать этот пример с использованием Grafana OSS и Docker Compose.

Чтобы создавать и управлять ресурсами оповещений с помощью Terraform, вам нужно выполнить следующие задачи.

Создайте API-ключ для настройки провайдера Terraform.
Создайте свои ресурсы оповещений в формате Terraform, для чего
- экспортируйте настроенные ресурсы оповещений
- или напишите схемы Terraform Alerting.
  
  По умолчанию вы не можете редактировать провижиненные ресурсы. Включите disable_provenance в ресурсе Terraform, чтобы разрешить изменения в интерфейсе Grafana.
Запустите terraform apply, чтобы провижинить ваши ресурсы оповещений.

Перед началом у вас должен быть доступный экземпляр Grafana и установленный Terraform на вашей машине.

Create an API key and configure the Terraform provider

Вы можете создать токен сервисного аккаунта для аутентификации Terraform в Grafana. Чтобы создать API-ключ для провижининга ресурсов оповещений, выполните следующие шаги.

Создайте новый сервисный аккаунт.
Назначьте роль или разрешение для доступа к Alerting provisioning API.
Создайте новый токен сервисного аккаунта.
Назовите и сохраните токен для использования в Terraform.

Теперь вы можете перейти в рабочий каталог для ваших конфигураций Terraform и создать файл с именем main.tf, например:

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

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

Замените следующие значения:

<grafana-url> на URL экземпляра Grafana.
<api-key> на ранее созданный API-токен.

Эта конфигурация Terraform устанавливает Grafana Terraform provider и аутентифицируется в вашем экземпляре Grafana с помощью API-токена. О других вариантах аутентификации, включая basic-аутентификацию, см. документацию по опции auth.

Для Grafana Cloud см. инструкции по управлению стеком Grafana Cloud с помощью Terraform. Для управления доступом на основе ролей см. Провижининг RBAC с помощью Terraform и роли провижининга оповещений (fixed:alerting.provisioning.*).

Create Terraform configurations for alerting resources

Grafana Terraform provider позволяет управлять следующими ресурсами оповещений.

Ресурс оповещения	Ресурс Terraform
Правила оповещения	grafana_rule_group
Contact points	grafana_contact_point
Шаблоны уведомлений	grafana_message_template
Дерево политик уведомлений	grafana_notification_policy
Mute timings	grafana_mute_timing

В этом разделе мы создадим конфигурации Terraform для каждого ресурса оповещения и продемонстрируем, как связать их вместе.

Add alert rules

Правила оповещения позволяют получать оповещения, выполняя запросы к любым бэкенд-источникам данных Grafana.

Сначала создайте источник данных для запросов и папку для хранения ваших правил.

В этом примере используется источник данных 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-имя папки.
Создайте или найдите правило оповещения, которое хотите импортировать в Grafana.

Экспортируйте группу правил оповещения в формате Terraform. Это экспортирует группу правил оповещения как ресурс Terraform grafana_rule_group.

Вы можете отредактировать экспортированный ресурс или создать ресурс с нуля.

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 связаны через значения uid в их конфигурациях Terraform. Значение uid будет сгенерировано случайным образом при провижининге.

Чтобы связать группу правил оповещения с соответствующим источником данных и папкой в этом примере, замените следующие значения полей:

<terraform_data_source_name> на terraform-имя ранее определённого источника данных.
<terraform_folder_name> на terraform-имя ранее определённой папки.

Продолжайте добавлять другие ресурсы Grafana или используйте Terraform CLI для провижининга.

Add contact points

Contact points — это получатели уведомлений об оповещениях.

Создайте или найдите contact points, которые хотите импортировать в Grafana. Либо напишите ресурс в коде, как показано в примере ниже.
Экспортируйте contact point в формате Terraform. Это экспортирует contact point как ресурс Terraform grafana_contact_point — при необходимости отредактируйте его.
В этом примере уведомления заглушаются на выходных.
terraform
```
 resource "grafana_contact_point" "<terraform_contact_point_name>" {
     name = "My contact point email"

     email {
         addresses               = ["<email_address>"]
     }
 }
```
Замените следующие значения полей:
- <terraform_contact_point_name> на terraform-имя contact point. Оно будет использоваться для ссылки на contact point в других ресурсах Terraform.
- <email_address> на адрес электронной почты для получения уведомлений об оповещениях.
Продолжайте добавлять другие ресурсы Grafana или используйте Terraform CLI для провижининга.

Add and enable notification templates

Шаблоны уведомлений позволяют настраивать уведомления об оповещениях для нескольких contact points.

Создайте или найдите группу шаблонов уведомлений, которую хотите импортировать в Grafana. Либо напишите ресурс в коде, как показано в примере ниже.
Экспортируйте группу шаблонов уведомлений как ресурс Terraform grafana_message_template.

В этом примере создаётся группа шаблонов уведомлений с именем 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
 }
```
Это позволяет contact points использовать шаблоны уведомлений ({{ define "<NAME>"}}) в пределах группы шаблонов уведомлений.

В предыдущем contact point включите шаблон, задав свойство email.message следующим образом.

 resource "grafana_contact_point" "<terraform_contact_point_name>" {
     name = "My contact point email"

     email {
         addresses               = ["<email_address>"]
         message                 = "{{ template \"custom_email.message\" .}}"
     }
 }

Продолжайте добавлять другие ресурсы Grafana или используйте Terraform CLI для провижининга.

Add mute timings

Mute timings приостанавливают уведомления об оповещениях на заранее определённые интервалы.

Создайте или найдите mute timings, которые хотите импортировать в Grafana. Либо напишите ресурс в коде, как показано в примере ниже.
Экспортируйте mute timing в формате Terraform. Это экспортирует mute timing как ресурс Terraform grafana_mute_timing — при необходимости отредактируйте его.
В этом примере уведомления отключаются на выходных.
terraform
```
 resource "grafana_mute_timing" "<terraform_mute_timing_name>" {
     name = "No weekends"

     intervals {
         weekdays = ["saturday", "sunday"]
     }
 }
```
Замените следующие значения полей:
- <terraform_mute_timing_name> на имя ресурса Terraform. Оно будет использоваться для ссылки на mute timing в дереве политик уведомлений Terraform.
Продолжайте добавлять другие ресурсы Grafana или используйте Terraform CLI для провижининга.

Add the notification policy tree

Политики уведомлений определяют, как маршрутизировать экземпляры оповещений к вашим contact points.

Warning
Since the policy tree is a single resource, provisioning it will overwrite all policies in the notification policy tree. However, it does not affect internal policies created when alert rules directly select a contact point.

Найдите дерево политик уведомлений по умолчанию. Либо напишите ресурс в коде, как показано в примере ниже.
Экспортируйте дерево политик уведомлений в формате Terraform. Это экспортирует его как ресурс Terraform grafana_notification_policy — при необходимости отредактируйте его.
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]
}
}
```
Чтобы настроить ранее созданные mute timing и contact point в дереве политик уведомлений, замените следующие значения полей:
- <terraform_data_source_name> на terraform-имя ранее определённого contact point.
- <terraform_folder_name> на terraform-имя ранее определённого mute timing.
Продолжайте добавлять другие ресурсы Grafana или используйте Terraform CLI для провижининга.

Enable editing resources in the Grafana UI

По умолчанию вы не можете редактировать ресурсы, провижиненные через Terraform, в Grafana. Это гарантирует, что ваш стек оповещений всегда остаётся синхронизированным с вашим кодом Terraform.

Чтобы сделать провижиненные ресурсы редактируемыми в интерфейсе Grafana, включите атрибут disable_provenance для ресурсов оповещений.

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
}
...

Provision Grafana resources with Terraform

Чтобы создать ранее описанные ресурсы оповещений в Grafana с помощью Terraform CLI, выполните следующие шаги.

Инициализируйте рабочий каталог, содержащий файлы конфигурации Terraform.
shell
```
terraform init
```
Эта команда инициализирует каталог Terraform, устанавливая Grafana Terraform provider, настроенный в файле main.tf.
Примените файлы конфигурации 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, чтобы проверить создание различных ресурсов.

More examples

Дополнительные примеры по концепции этого руководства:

Попробуйте демонстрацию провижининга ресурсов оповещений в Grafana OSS с использованием Terraform и Docker Compose.
Ознакомьтесь со всеми доступными опциями и примерами схем Terraform Alerting в документации Grafana Terraform Provider.
Ознакомьтесь с руководством по управлению стеком Grafana Cloud с помощью Terraform.

Была ли эта страница полезна?

Написать на docs@glaber.ru

Справка и поддержка

Сообщество