Grafanaのdatasourceとdashboardは従来REST APIか、GUIを通じてしかexport/importできなくて、Git等で管理するのに少し工夫が必要だったのだけど、v5.0からファイルでの管理に対応した。それについてドキュメント読んでメモしただけの記事。
Provisioning | Grafana Documentation
ファイルで管理できると、AnsibleやDockerとの相性も良くなってとても楽。
Datasources
/etc/grafana/provisioning/datasources/hoge.yml に設定を以下のように書く。datasourceが複数ある場合、ファイルは分割しても良いし、 datasources にmapで複数指定してもよい。
apiVersion: 1
datasources:
- name: timeseriesData
type: influxdb
access: proxy
orgId: 1
url: http://192.0.1.1:8086
user: user
password: password
database: timeseries
isDefault: true
editable: false
version: 1
設定を更新したときに version をincrementしておけば、古いversionで新しいversionは上書きできなくなっているので安心、みたいなこともドキュメントには書かれているのだが、どうも上手く動かなくて使い方がわからない。
editable がデフォルトで false になっており、yamlでprovisioningした設定は、GUIからは書き換えできなくなっている。これはyamlからその設定を削除した後も有効。yamlで追加したdatasourceを消すには、 editable: true にしてGUIから消すか、 delete_datasources に設定するかの2択。
一意性
name で判断されている。既存のdatasourceと同じ name を持つ設定をyamlで準備した場合、yamlの値が優先されて、上書きされてしまうため注意が必要。
Dashboards
こちらは2箇所に設定が必要。まず /etc/grafana/provisioning/dashboards/hoge.yml を置く。
apiVersion: 1
providers:
- name: 'hoge'
orgId: 1
folder: ''
type: file
disableDeletion: true
editable: true
options:
path: /var/lib/grafana/dashboards
ここで書いた name はGUIだと特にどこでも使われていないと思うので、なんでもいい。これは単に、実際のdashboardのjsonを providers[0].options.path に置きますよという宣言をしているだけ。あとは diableDeletion や editable はお好みに応じて。ドキュメントに各設定値の詳細が書かれていないので、今のところ挙動がわかりにくいが、disableDeletion: true にしておくと、jsonを削除してもdashboardは削除されなくなる。
実際のjsonは、この場合では /var/lib/grafana/dashboards に1つずつ配置する。このjsonは、従前のバージョンからGUIで出力できていた、あの書式で良い。あまりGrafana dashboardをjsonでイチから書く人もいないと思うので、一旦GUIで作ってからexportすればOK。但し、exportした際には付与される id という値が、ファイルでのprovisioningの場合は不要となっているので、削っておく必要がある。
一意性
uid で管理される。uidはGUIから作成したdashboardだとランダムに採番されていて、yamlから作成するときはjsonの中で好きに採番できる（採番しなくてもOKで、その場合はやはりランダムになる）。すでに存在するuidと同じuidでjson設定を書いた場合、そのuidのdashboardが強制的に更新される。uidはdashboardのURLに含まれるため、複数のGrafanaを立てて、同じグラフを双方で表示するとき、一意なURL採番をするのに役立つ。
ただし、注意するべきは title も一意である必要があるということ。例えば1つのGrafanaサーバーに、 title が同一で、 uid は異なるdashboard設定を複数用意しても、後発の設定は反映されない。GUIですでに存在するdashboardの設定をjsonファイルで配置し、別uidを振ったとしても、既存の方のdashboardを一度削除しないことには、jsonの方は反映されない。