点击驱动的 Grafana 一直可用,直到你第一次需要第二份副本、一次回滚,或是回答”这个面板是谁改的?”。本指南勾勒出如何用文件而不是点击来运行 Grafana,这样在你编写任何 YAML 之前,就知道每种资源该用哪种机制。

为什么 UI 会成为问题

当仪表板、数据源和告警都是手工创建时,随着时间推移会出现三个问题:

• 没有任何东西可复现。 状态存在于 Grafana 的数据库中。重建一个实例意味着把每一次点击重做一遍。
• 变更不可见。 没有审查步骤,除了 Grafana 自己的版本日志所保留的内容之外也没有历史。
• 环境发生漂移。 Staging 和 production 慢慢分叉,没有人说得清是如何分叉的。

解决办法是把数据库当作缓存,把仓库当作事实。Grafana 所需的一切,要么在启动时从文件 provision,要么由读取文件的工具应用。

各层

层	格式	控制什么	由谁应用
服务器配置	grafana.ini 和 GF_* 环境变量	端口、数据库、认证、SMTP、日志、功能开关	Grafana 启动时
数据源 provisioning	YAML	数据源及其凭据	Grafana 启动时
仪表板 provisioning	YAML provider + JSON 文件	仪表板和文件夹	Grafana,按间隔重新扫描
告警 provisioning	YAML	告警规则、联系点、策略、静默时段、模板	Grafana 启动时
插件 provisioning	YAML	已安装的插件应用的设置	Grafana 启动时
Terraform	HCL	任何有 API 的东西:文件夹、数据源、仪表板、告警、团队、service account	terraform apply
Grafana Operator	Kubernetes 自定义资源	实例、文件夹、仪表板、数据源、告警规则	集群中的控制器
Git Sync	一个 Repository 资源	保存在 Git 仓库中并双向同步的仪表板	Grafana 自身

你应该用哪一种?

• 容器或虚拟机中的单个 Grafana,小团队: 服务器配置加文件 provisioning。没有额外的活动部件。
• 使用 GitOps(Flux 或 Argo CD)的 Kubernetes: 用 Grafana Helm chart 部署实例,provisioning 文件作为 ConfigMap;如果你希望每个仪表板和数据源都是自己的 Kubernetes 对象,则使用 Grafana Operator。
• 多个实例,或 Grafana Cloud: Terraform,因为它还可以创建 stack、service account 和团队。
• 由许多人编写的仪表板: Git Sync,或者像 Grafana Foundation SDK 这样生成 JSON 的代码库。

这些可以很好地混用。常见的配置是用文件 provision 数据源和告警,再用 Git Sync 或 Terraform 管理仪表板。

文件无法做到的事

有些资源没有 provisioning 文件格式。请为此做好计划:

• 用户、团队、组织和 service account 通过 API 或 Terraform 创建(或通过带有 SSO 和角色映射的身份提供商)。
• 文件夹和仪表板权限 通过 API、Terraform 或 Operator 管理。
• 第一个管理员密码 只在首次运行时设置,所以之后更改它需要 CLI 或 API 调用。

认证指南和 Terraform 指南介绍了变通方法。

Provisioned 意味着被锁定

被 provision 的资源本意是由文件拥有。数据源可以标记为 editable: false,来自 provider 的仪表板可以拒绝 UI 保存,被 provision 的告警资源则根本无法在 UI 中编辑。这正是关键所在:如果有人可以手动更改它们,Git 就不再是事实来源了。请记住,UI 对于探索数据和起草面板仍然有用,仪表板指南中的创作工作流展示了如何将这些草稿带回 Git。

一次变更的心智模型

1. 在仓库中编辑一个文件(仪表板 JSON、数据源 YAML、告警规则)。
2. 打开拉取请求,审查 diff,合并。
3. 交付机制应用它:容器重启、仪表板重新扫描、Flux 协调,或 terraform apply。
4. Grafana 自己的数据库被更新以匹配。如果出了问题,回退这次提交。

接下来去哪里

通过 compose 文件在本地运行一个 Grafana(下一篇指南),学习配置规则,然后逐个添加数据源、仪表板和告警。参考资料请见 Grafana 文档。