Kibana 仪表板即代码：在 Elastic 9.4 中用于 Kibana 仪表板的 GitOps、漂移检测与 Terraform

作者来自 Elastic Teresa Alvarez Soler, Omer Kushmaro 及 Devon ThomsonElastic 9.4 推出了类型化的 Dashboards API以及原生 Terraform 资源这使得 Kibana 仪表板首次具备漂移检测、PR 可审查差异以及基于 Git 的回滚能力。通过一个统一解决方案观察、保护并搜索你的数据。从应用监控到威胁检测Kibana 是你用于关键用例的多功能平台。立即开始你的 14 天免费试用。Elastic 9.4 推出了一个专门设计的 Kibana Dashboards API包含 5 个类型化 endpoint、针对 12 种可视化类型的校验 schema以及一个新的 elasticstack_kibana_dashboard Terraform 资源为 Kibana 仪表板带来漂移检测、plan diff、按环境部署以及基于 Git 的回滚能力。你可以用 HCL 定义 dashboard在 pull request 中审查变更并通过回滚 commit 来恢复版本。下面是它的工作方式。为什么仪表板需要 API现有的 Saved Object API 会把 dashboard 以单个字符串化 JSON blob的形式导出可视化状态、内部引用、UUID 和元数据全部混杂在一起。修改一个 Kibana Lens 图表中的字段就需要解析 200 行原本并不适合人工阅读的内部状态。你无法方便地对它进行 diff、在 pull request 中审查或以程序方式修改它。这使得标准GitOps 工作流无法成立没有 drift detection没有跨环境的自动推进也无法在不手动覆盖整个文档的情况下回滚到已知良好状态。对于大语言模型LLMs来说这同样不友好。Saved Object 格式过于复杂且容易出错模型很难可靠生成或修改因此需要一个更简单、带校验的 schema这也是我们在 以及用于第三方工具集成的 dashboard skills 中进行自然语言仪表板生成的基础。新 Dashboards API 提供的能力该 API 可以与现有 dashboards 一起使用并不局限于通过新界面创建的 dashboard。五个 endpoint 覆盖完整生命周期创建新的 dashboardPOST /api/dashboards。读取已有 dashboardGET /api/dashboards/{id}。更新已有 dashboard或在 ID 不存在时创建新 dashboardupsertPUT /api/dashboards/{id}。删除 dashboardDELETE /api/dashboards/{id}。列出所有 dashboard支持分页与查询参数GET /api/dashboards。与传统 Saved Object API 的不同之处每个 panel 都有类型化 schema。每种可视化类型XY 图、metric、pie、gauge、heatmap、data table、treemap、mosaic、waffle、tag cloud、region map都有各自的校验 schema 和合理默认值。同时也支持 markdown panel、controls 和 drilldown。ES|QL 与 data view 支持。每个 visualization 可以基于 data view 或 Elasticsearch Query LanguageES|QL查询两种模式在 schema 中被清晰分离。dashboard 级别 filters。支持 condition filtersis、is_one_of、range、exists、group filtersand/or 嵌套、raw Query DSL filters 以及 spatial filters全部在 dashboard 层级进行类型化定义。写入时结构校验。POST 和 PUT 会在写入阶段进行验证因此错误在写入时就会暴露而不是在渲染时才出现。布局控制。panel 使用 48 列 grid 定位dashboard 可以按可折叠 section 进行组织。library panels。panel 可以仅存在于某个 dashboard 中也可以保存到 library 以便在多个 dashboard 中复用。API 同时支持这两种 panel 类型。Kibana Dashboards API 是如何构建的transforms 层在项目一开始我们很快发现 Saved Objects API 之所以难以使用最大的问题在于 dashboard 内容被字符串化了。例如dashboard 的整个 panels 数组会被存储在一个名为 “panelsJSON” 的字段中这个字段可能长达数千甚至数万字符而且全部挤在一行里。我们亲切地把这些字段称为 “JSON Bags”。如果我们能够停止对这些 key 的字符串化过程而是直接把 JSON 存入 Elasticsearch那么很多问题本可以解决。不幸的是当我们反字符串化这些 JSON 并真正看到其中内容时我们发现它其实是一团混乱的东西。Kibana 从一开始就存储用户创建的 UI 内容。这些内容的唯一目的就是让 UI 能够在之后重新恢复它们。由于真实的存储形态并不重要它们被直接以 UI 状态的快照形式写入 Elasticsearch。UI state 是为创建它的特定 UI 优化的并不适合被直接阅读。像深层嵌套、带有随机生成 ID 的对象、并行数组以及不同状态片段之间的内部引用等结构在 UI 中是有用的但在可读性上是有害的。在这里我们面临一个选择保留现有 UI 代码并为 public endpoints 构建一个新的替代 API schema绕过现有 dashboard 系统并只实现其中最常用的功能。或者在现有 dashboard 系统中注入一个新的 API schema并构建 middleware使同一套 API schema 同时支撑 UI 和 public endpoints。我们选择了第二种方案并开始了一项巨大的工程将现有 UI state 中杂乱无章的每个 panel 的每一个 key 逐步提炼并重新定义为一个我们可以正式发布为 API schema 的结构。这个过程在很长一段时间内由多个团队在生产代码中协同完成。在整个过程中向后兼容性被放在极高优先级因为用户每天都在保存和加载 dashboards。实现这一切的中间层被称为 transforms layer它负责在 legacy 的字符串化 state 结构和更清晰的 API 结构之间进行双向转换。针对 dashboard 可以承载的每一种 panel都注册了 transform 函数。负责这些 panel 的团队会在每一个 PR 中逐步优化 schema并同步更新 UI确保 UI 始终能够正常运行。随着每种 panel 注册其 transform 函数它也可以注册一个 schema这个 schema 会成为 public Dashboards API contract 的一部分。通过这种方式注册的 schema 必须是完整的以降低未来 API 发生破坏性变更的风险。如果某个 panel 类型没有注册 schema那么它将不会出现在 public API response 中。这使我们可以逐步将更多内容纳入 public API从 tech preview 开始扩展同时确保依赖该 API 的用户可以信任其结构不会变化。使用 Kibana Dashboards API操作演示Kibana Dashboards API 在 Elastic 9.4 中可用并且可以与现有 dashboards 一起使用。最佳起点是 Dashboards API 文档在那里你可以找到所有 schema 定义和示例。下面的示例使用 Kibana sample logs 数据来演示该 API这并不是一个真实的 GitOps 工作流而是一个用于理解其工作方式的简单示例。打开一个 dashboard然后点击顶部菜单中的Export JSON。这个 dashboard 包含一个 control 和两个 section其中一个 section 包含两个 metrics另一个 section 包含两个 time series。你会看到这个 dashboard 的 JSON 以 flyout 的形式显示出来。现在点击Open in Console。你会被重定向到 Developer tools并且一个新的 POST 请求会自动预填好 HTTP request。在 POST 请求的 URL 中包含 space ID。POST kbn:/s/production/api/dashboards?前往目标 space查看 dashboard 是否已创建。Terraform 支持将 dashboards 作为原生 HCL 管理Elastic Stack Terraform provider 提供了一个新的 elasticstack_kibana_dashboard 资源它将 Dashboards API 映射为原生 Terraform HCL。这意味着你可以对 dashboards 使用 terraform plan、terraform apply、drift detection、import以及 Terraform 标准的生命周期操作。该 provider 目前还没有覆盖所有 API 能力它优先支持 GitOps 工作流中最关键的功能。Terraform 示例一个用 Terraform HCL 定义的 Kibana dashboard 示例从基础开始一个 dashboard包含一个用于追踪请求数量的 time series 图表、一个展示 KPI 的 metric panel以及一个用于上下文说明的 markdown panel。resource elasticstack_kibana_dashboard service_overview { title Service Overview description Key metrics for the payments service tags [production, payments] time_range { from now-1h, to now } refresh_interval { pause false, value 30000 } query { language kql, text service.name:payments } panels [ { type vis grid { x 0, y 0, w 32, h 15 } xy_chart_config { axis { x { title { visible true } } y { title { visible true } scale linear domain_json jsonencode({ type fit }) } } legend { visibility visible, inside false, position right } fitting { type none } decorations { fill_opacity 0.3 } query { language kql, expression } layers [{ type area data_layer { ignore_global_filters false sampling 1 data_source_json jsonencode({ type data_view_spec, index_pattern logs-* }) y [{ config_json jsonencode({ operation count, empty_as_null true, color { type auto } }) }] } }] } }, { type vis grid { x 32, y 0, w 16, h 15 } metric_chart_config { ignore_global_filters false sampling 1 data_source_json jsonencode({ type data_view_spec, index_pattern logs-*, time_field timestamp }) query { language kql, expression } metrics [{ config_json jsonencode({ type primary, operation count, empty_as_null false, color { type auto }, format { type number, decimals 2, compact false } }) }] } } ] }这是可读的、可审查的也是可 diff 的。当有人修改时间范围或添加 filter 时terraform plan 的输出会精确告诉你发生了什么变化。Terraform 中的 dashboard access controlTerraform provider 支持 dashboard 的 access control 模型允许你限制写入权限并设置 ownershipresource elasticstack_kibana_dashboard protected { title Production SLOs # ... access_control { access_mode write_restricted } }当 access_mode 设置为 write_restricted 时只有创建者可以进行更改。这在生产环境的 dashboards 中尤其有用可以确保所有变更都必须通过 Terraform pipeline 流转。Kibana dashboards 的 GitOps 工作流借助新的 Dashboards API 和 Terraform 支持你现在可以像对待其他基础设施资源一样对待 dashboards用 HCL定义dashboards与 Elasticsearch indices、data views 和 alerting rules 一起管理。通过 pull request审查变更terraform plan 会清晰展示每个 visualization 的变化。使用 Terraform workspaces 或按环境划分的 variable files 在不同环境中部署。当有人在 Kibana UI 中手动修改 dashboard 时可以通过 terraform plan检测 drift并显示差异。通过回滚commit 并重新执行 terraform apply 来恢复到历史状态。Elastic 用户现在可以享受支持 GitOps 的 dashboards拥有一种类型化、HCL 原生的体验不仅仅是 dashboard 管理本身。开始使用 Terraform providerelasticstack_kibana_dashboard 资源要求Elastic Stack 9.4 或更高版本并可在最新版本的 Elastic Stack Terraform provider 中使用。开始步骤如下配置你的 provider使其能够连接 Kibanaterraform { required_providers { elasticstack { source elastic/elasticstack version ~ 0.14 } } } provider elasticstack { kibana {} }使用上面的任意示例定义你的第一个 dashboard。运行terraform plan 来预览变更然后运行 terraform apply 来创建资源。将已有dashboards 导入Terraform stateterraform import elasticstack_kibana_dashboard.my_dashboard space_id/dashboard_id完整的资源 schema 和文档请访问 Terraform Registry。Kibana Dashboards API 路线图Dashboards API 在 Elastic 9.4 中处于技术预览technical preview阶段API 本身以及 Terraform provider 都在持续演进中。未来规划包括API 将支持所有 panel 类型。目前仍有一些 panel 尚未支持 API例如 Links panel、Machine Learning panels、Alerts、Log analysis panels、Vega visualization 以及 Maps。Terraform 中增加更多 panel 类型。为 image、links、Service Level ObjectiveSLO以及 Synthetics panels 提供类型化的 HCL 配置块这些类型在 API 中已经支持。Terraform 中支持 dashboard 级别 filters。包括 filter pills、controls 和 drilldowns这些能力在 API 中已经支持。欢迎尝试并告诉我们你的反馈。你可以通过顶部菜单的 Submit Feedback 图标提交反馈在 Terraform provider 的 GitHub 仓库中提交 issue或者加入 Discuss 社区参与讨论。我们期待你的反馈原文https://www.elastic.co/search-labs/blog/kibana-dashboards-as-code-terraform-api