Провижининг Grafana
В Grafana есть активная система провижининга, использующая конфигурационные файлы. Вы можете описывать источники данных и дашборды с помощью файлов, которые можно версионировать, что делает подход GitOps более естественным.
Note
О расширенных вариантах as code, таких как Infrastructure as code, Git Sync или файловый провижининг on-prem, см. Deploy, configure and provision Grafana with as-code workflows.
Конфигурационный файл
О том, что можно настроить в grafana.ini, см.
Configuration.
Расположение конфигурационного файла
Grafana читает конфигурацию по умолчанию из <WORKING DIRECTORY>/conf/defaults.ini.
Пользовательскую конфигурацию Grafana читает из <WORKING DIRECTORY>/conf/custom.ini. Путь к пользовательской конфигурации можно переопределить опцией --config.
Note
Пакеты Deb и RPM устанавливают конфигурационный файл в
/etc/grafana/grafana.ini. Скрипт init.d Grafana устанавливает опцию--configв этот путь.
Использование переменных окружения
Во всей конфигурации провижининга можно использовать подстановку переменных окружения. Синтаксис переменной окружения — $ENV_VAR_NAME или ${ENV_VAR_NAME}.
Применяются следующие правила:
- Используйте переменные окружения только для значений конфигурации. Не используйте их для ключей или крупных частей структуры конфигурационного файла.
- Используйте переменные окружения в конфигурации провижининга дашбордов, но не в самих файлах определения дашбордов.
В следующем примере порт URL источника данных, имя пользователя и пароль подставляются из переменных окружения:
datasources:
- name: Graphite
url: http://localhost:$PORT
user: $USER
secureJsonData:
password: $PASSWORD
Использование специального символа $
Система провижининга Grafana считает любой набор символов после $ именем переменной.
В процессе подстановки Grafana:
- Заменяет переменные, использующие синтаксис
${ENV_VAR_NAME}. - Затем заменяет переменные, использующие синтаксис
$ENV_VAR_NAME.
Если ваши данные содержат символ $, например Pa$sw0rd, и вы используете переменную окружения, применяйте синтаксис $ENV_VAR_NAME, чтобы избежать двойной подстановки. Если использовать синтаксис ${ENV_VAR_NAME}, значение сначала будет заменено на Pa$sw0rd, а затем ещё раз — на Pa, поскольку $sw0rd будет воспринято как ещё одна переменная.
Если нужно получить буквальное значение Pa$sw0rd, экранируйте символ $ двойным $$: Pa$$sw0rd.
В следующем примере показано, как выполняется подстановка переменных при условии PASSWORD=Pa$sw0rd:
datasources:
- name: Graphite
secureJsonData:
password1: $PASSWORD # Resolved as Pa$sw0rd
password2: ${PASSWORD} # Resolved as Pa
password3: 'Pa$$sw0rd' # Resolved as Pa$sw0rd
password4: 'Pa$sw0rd' # Resolved as Pa
Источники данных
Управлять источниками данных в Grafana можно, добавляя YAML-файлы конфигурации в каталог provisioning/datasources.
Каждый конфигурационный файл содержит список источников данных под ключом datasources, которые нужно добавить или обновить при запуске.
Если источник данных уже существует, Grafana перенастраивает его в соответствии с конфигурационным файлом провижининга.
Также можно перечислить источники данных для автоматического удаления с помощью ключа deleteDatasources.
Grafana удаляет источники данных, перечисленные в deleteDatasources, до добавления или обновления тех, что указаны в списке datasources.
Можно настроить Grafana так, чтобы провижининг-источники данных автоматически удалялись при их исключении из файла провижининга.
Для этого добавьте prune: true в корень файла провижининга источников данных.
При такой конфигурации Grafana также удаляет провижининг-источники данных, если вы удалите файл провижининга целиком.
Запуск нескольких экземпляров Grafana
Если вы запускаете несколько экземпляров Grafana, добавьте номер версии каждому источнику данных в конфигурации и увеличивайте его при обновлении конфигурации.
Grafana обновляет только те источники данных, номер версии которых равен или меньше указанного в конфигурационном файле.
Это предотвращает перезапись старыми конфигурациями более новых, если у вас есть разные версии файла datasource.yaml, в которых не заданы номера версий, и вы одновременно перезапускаете экземпляры.
Пример конфигурационного файла источника данных
В этом примере выполняется провижининг источника данных Graphite:
# Configuration file version
apiVersion: 1
# List of data sources to delete from the database.
deleteDatasources:
- name: Graphite
orgId: 1
# Mark provisioned data sources for deletion if they are no longer in a provisioning file.
# It takes no effect if data sources are already listed in the deleteDatasources section.
prune: true
# List of data sources to insert/update depending on what's
# available in the database.
datasources:
# <string, required> Sets the name you use to refer to
# the data source in panels and queries.
- name: Graphite
# <string, required> Sets the data source type.
type: graphite
# <string, required> Sets the access mode, either
# proxy or direct (Server or Browser in the UI).
# Some data sources are incompatible with any setting
# but proxy (Server).
access: proxy
# <int> Sets the organization id. Defaults to orgId 1.
orgId: 1
# <string> Sets a custom UID to reference this
# data source in other parts of the configuration.
# If not specified, Grafana generates one.
uid: my_unique_uid
# <string> Sets the data source's URL, including the
# port.
url: http://localhost:8080
# <string> Sets the database user, if necessary.
user:
# <string> Sets the database name, if necessary.
database:
# <bool> Enables basic authorization.
basicAuth:
# <string> Sets the basic authorization username.
basicAuthUser:
# <bool> Enables credential headers.
withCredentials:
# <bool> Toggles whether the data source is pre-selected
# for new panels. You can set only one default
# data source per organization.
isDefault:
# <map> Fields to convert to JSON and store in jsonData.
jsonData:
# <string> Defines the Graphite service's version.
graphiteVersion: '1.1'
# <bool> Enables TLS authentication using a client
# certificate configured in secureJsonData.
tlsAuth: true
# <bool> Enables TLS authentication using a CA
# certificate.
tlsAuthWithCACert: true
# <map> Fields to encrypt before storing in jsonData.
secureJsonData:
# <string> Defines the CA cert, client cert, and
# client key for encrypted authentication.
tlsCACert: '...'
tlsClientCert: '...'
tlsClientKey: '...'
# <string> Sets the database password, if necessary.
password:
# <string> Sets the basic authorization password.
basicAuthPassword:
# <int> Sets the version. Used to compare versions when
# updating. Ignored when creating a new data source.
version: 1
# <bool> Allows users to edit data sources from the
# Grafana UI.
editable: false
Примеры провижининга конкретных источников данных см. в документации соответствующего источника данных.
JSON-данные
Не у всех источников данных одинаковые параметры конфигурации: в файле провижининга источника данных полями являются только самые распространённые.
Чтобы выполнить провижининг остальных параметров источника данных, включите их как JSON в поле jsonData.
Общие параметры встроенных базовых источников данных:
Note
Источники данных, помеченные HTTP*, взаимодействуют по протоколу HTTP, что охватывает все базовые плагины источников данных, кроме MySQL, PostgreSQL и MSSQL.
Примеры JSON-данных конкретных источников данных см. в документации соответствующего источника данных.
Secure JSON data
Secure JSON data — это набор параметров, зашифрованных с помощью секретного ключа. Шифрование скрывает JSON-данные от пользователей Grafana. Secure JSON data следует использовать для хранения TLS-сертификатов и паролей для HTTP-запросов к источникам данных. Все эти параметры необязательны.
Note
Тег HTTP* обозначает источники данных, взаимодействующие по протоколу HTTP, включая все базовые плагины источников данных, кроме MySQL, PostgreSQL и MSSQL.
Пользовательские HTTP-заголовки для источников данных
Вы можете добавлять HTTP-заголовки ко всем запросам, отправляемым источникам данных, управляемым провижинингом Grafana.
Настройте имя заголовка в поле jsonData, а значение заголовка — в secureJsonData.
В следующем примере заголовку HeaderName задаётся значение HeaderValue, а заголовку Authorization — значение Bearer XXXXXXXXX:
apiVersion: 1
datasources:
- name: Graphite
jsonData:
httpHeaderName1: 'HeaderName'
httpHeaderName2: 'Authorization'
secureJsonData:
httpHeaderValue1: 'HeaderValue'
httpHeaderValue2: 'Bearer XXXXXXXXX'
Плагины
Управлять плагинами-приложениями в Grafana можно, добавляя один или несколько YAML-файлов конфигурации в каталог provisioning/plugins.
Каждый конфигурационный файл содержит список apps, которые Grafana настраивает при запуске.
Grafana настраивает каждое приложение согласно конфигурации в файле.
Note
Эта возможность позволяет выполнять провижининг конфигураций плагинов, а не самих плагинов. Чтобы использовать провижининг конфигураций плагинов, плагин должен быть уже установлен.
Пример конфигурационного файла плагина
apiVersion: 1
apps:
# <string> the type of app, plugin identifier. Required
- type: raintank-worldping-app
# <int> Org ID. Default to 1, unless org_name is specified
org_id: 1
# <string> Org name. Overrides org_id unless org_id not specified
org_name: Main Org.
# <bool> disable the app. Default to false.
disabled: false
# <map> fields that will be converted to json and stored in jsonData. Custom per app.
jsonData:
# key/value pairs of string to object
key: value
# <map> fields that will be converted to json, encrypted and stored in secureJsonData. Custom per app.
secureJsonData:
# key/value pairs of string to string
key: value
Дашборды
Управлять дашбордами в Grafana можно, добавляя один или несколько YAML-файлов конфигурации в каталог provisioning/dashboards.
Каждый конфигурационный файл содержит список providers, которые Grafana использует для загрузки дашбордов из локальной файловой системы.
Пример конфигурационного файла дашбордов
apiVersion: 1
providers:
# <string> an unique provider name. Required
- name: 'a unique provider name'
# <int> Org id. Default to 1
orgId: 1
# <string> name of the dashboard folder.
folder: ''
# <string> folder UID. will be automatically generated if not specified
folderUid: ''
# <string> provider type. Default to 'file'
type: file
# <bool> disable dashboard deletion
disableDeletion: false
# <int> how often Grafana will scan for changed dashboards
updateIntervalSeconds: 10
# <bool> allow updating provisioned dashboards from the UI
allowUiUpdates: false
options:
# <string, required> path to dashboard files on disk. Required when using the 'file' type
path: /var/lib/grafana/dashboards
# <bool> use folder names from filesystem to create folders in Grafana
foldersFromFilesStructure: true
При запуске Grafana обновляет или создаёт все дашборды, найденные по настроенному пути. Эти файлы могут описывать дашборд с помощью JSON-представления дашборда:
{
"dashboard": {
"id": null,
"uid": "example-dashboard",
"title": "Production Overview",
"tags": ["production", "monitoring"],
"timezone": "browser",
"schemaVersion": 16,
"version": 0,
"refresh": "30s"
},
"folderUid": "monitoring-folder",
"overwrite": true
}
Либо с использованием формата Kubernetes, например kubernetes-dashboard.json:
{
"kind": "Dashboard",
"apiVersion": "dashboard.grafana.app/v1",
"metadata": {
"name": "dashboard-uid"
},
"spec": {
"title": "Dashboard title",
"panels": [
{
"gridPos": {
"h": 13,
"w": 24,
"x": 0,
"y": 0
},
"options": {
"content": "<div><h1>Example panel</h1></div>",
"mode": "html"
},
"transparent": true,
"type": "text"
}
]
}
}
Для провижининга дашбордов v2 / динамических дашбордов вы обязаны использовать формат ресурса Kubernetes.
Note
Если не задать поле
folder, Grafana устанавливает дашборды на корневом уровне.
Обнаружение изменений в файлах провижининг-дашбордов
После провижининга дашбордов Grafana проверяет файловую систему на изменения и при необходимости обновляет дашборды.
Механизм, который Grafana при этом использует, зависит от значения updateIntervalSeconds:
- Больше 10 секунд: Grafana опрашивает путь с этим интервалом.
- 10 секунд или меньше: Grafana следит за изменениями в файловой системе и обновляет дашборды при их обнаружении.
Note
Когда
updateIntervalSecondsравно 10 или меньше, Grafana полагается на события файловой системы для обнаружения изменений. В зависимости от вашей файловой системы и способа монтирования или синхронизации файлов дашбордов (например, bind-монтирование в Docker или некоторые сетевые файловые системы) эти события могут не доходить до Grafana. Чтобы обойти это, задайтеupdateIntervalSecondsбольше 10, чтобы принудительно включить опрос, либо измените настройку так, чтобы события файловой системы распространялись.
Внесение изменений в провижининг-дашборд
Вы можете вносить изменения в провижининг-дашборд через интерфейс Grafana, но автоматически сохранить изменения обратно в источник провижининга невозможно.
Если allowUiUpdates установлено в true и вы вносите изменения в провижининг-дашборд, то при сохранении дашборда Grafana сохраняет изменения в своей базе данных.
Caution
Если вы сохраните провижининг-дашборд в интерфейсе, а затем обновите источник провижининга, Grafana всегда перезапишет дашборд в базе данных версией из файла провижининга. Grafana игнорирует свойство
versionв JSON-файле, даже если оно меньше, чем у дашборда в базе данных.
Caution
Если вы сохраните провижининг-дашборд в интерфейсе и удалите источник провижининга, Grafana удалит дашборд из базы данных, если только для параметра
disableDeletionне задано значениеtrue.
Если для allowUiUpdates задано значение false, вы не сможете сохранять изменения в провижининг-дашборд.
При попытке сохранить изменения в провижининг-дашборд Grafana выводит диалоговое окно Cannot save provisioned dashboard.
Grafana предоставляет возможности экспорта JSON-определения дашборда. Чтобы экспортировать JSON-определение дашборда, выполните следующие шаги:
-
При сохранении нажмите Advanced options, чтобы развернуть раздел, и затем сделайте следующее:
- Model: выберите Classic или V2 Resource. Выбирайте Classic, если планируете использовать дашборд в Grafana v12.4 или более ранней версии.
- Format: только для V2 Resource — выберите JSON или YAML
-
Нажмите Copy JSON to Clipboard или Save JSON to file.
Следующий скриншот иллюстрирует это поведение.
Grafana удаляет поле id из JSON дашборда, чтобы упростить рабочий процесс провижининга.
После этого вы синхронизируете изменения дашборда обратно в источник провижининга.
Переиспользуемые URL дашбордов
Если дашборд в JSON-файле содержит UID, Grafana обновляет в базе данных дашборд с этим UID. Это позволяет переносить дашборды между экземплярами Grafana и сохранять согласованные URL дашбордов. При запуске Grafana создаёт или обновляет все дашборды, доступные в настроенных каталогах.
Caution
С помощью провижининга можно перезаписать существующие дашборды.
Будьте осторожны: не используйте один и тот же
titleнесколько раз в пределах каталога или один и тот жеuidв пределах одного экземпляра Grafana, чтобы избежать несогласованного поведения.
Провижининг структуры каталогов из файловой системы в Grafana
Если вы уже храните дашборды в каталогах Git-репозитория или файловой системы и хотите видеть те же имена каталогов в меню Grafana, используйте параметр foldersFromFilesStructure.
Например, чтобы воспроизвести следующую структуру дашбордов из файловой системы в Grafana:
/etc/dashboards
├── /server
│ ├── /common_dashboard.json
│ └── /network_dashboard.json
└── /application
├── /requests_dashboard.json
└── /resources_dashboard.json
используйте следующий конфигурационный файл провижининга:
apiVersion: 1
providers:
- name: dashboards
type: file
updateIntervalSeconds: 30
options:
path: /etc/dashboards
foldersFromFilesStructure: true
Grafana создаст в интерфейсе каталоги server и application.
Чтобы использовать foldersFromFilesStructure, необходимо снять параметры folder и folderUid.
Чтобы разместить дашборды на корневом уровне, храните их в корне вашего path.
Note
Поддерживаются вложенные структуры каталогов: иерархия каталогов на диске воссоздаётся в Grafana.
Например,
folderTwo/folderThree/dashboard3.jsonсоздаёт каталогfolderTwo, содержащий каталогfolderThree, который содержит дашборд.Глубина вложенности каталогов ограничена
4уровнями.
Alerting
О провижининге Grafana Alerting см. Provision Grafana Alerting resources.
Поддерживаемые параметры
В следующих разделах подробно описаны поддерживаемые параметры и защищённые параметры для каждого типа уведомлений об алертах.
В YAML провижининга используйте settings для параметров и secure_settings для защищённых параметров.
Grafana шифрует защищённые параметры в базе данных.
Уведомление об алертах pushover
Уведомление об алертах discord
Уведомление об алертах slack
Уведомление об алертах victorops
Уведомление об алертах kafka
Уведомление об алертах LINE
Уведомление об алертах MQTT
Конфигурация TLS
Уведомление об алертах pagerduty
Уведомление об алертах sensu
Уведомление об алертах sensugo
Уведомление об алертах prometheus-alertmanager
Уведомление об алертах teams
Уведомление об алертах dingding
Уведомление об алертах email
Уведомление об алертах opsgenie
Уведомление об алертах telegram
Уведомление об алертах threema
Уведомление об алертах webhook
Конфигурация TLS
Конфигурация подписи HMAC
Уведомление об алертах googlechat
Уведомление об алертах Cisco Webex Teams
Grafana Enterprise
Grafana Enterprise поддерживает:
- Провижининг ролевого доступа на основе ролей с помощью Grafana
- Провижининг ролевого доступа на основе ролей с помощью Terraform
Инструменты управления конфигурацией
Сообщество Grafana поддерживает библиотеки для многих популярных инструментов управления конфигурацией.