当前位置： 首页 > news >正文

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

news 2026/5/28 4:22:50

作者：来自 Elastic Teresa Alvarez Soler, Omer Kushmaro 及 Devon Thomson

Elastic 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 覆盖完整生命周期：

  • 创建新的 dashboard（POST /api/dashboards）。
  • 读取已有 dashboard（GET /api/dashboards/{id}）。
  • 更新已有 dashboard，或在 ID 不存在时创建新 dashboard（upsert）（PUT /api/dashboards/{id}）。
  • 删除 dashboard（DELETE /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 Language（ES|QL）查询，两种模式在 schema 中被清晰分离。
  • dashboard 级别 filters。支持 condition filters（is、is_one_of、range、exists）、group filters（and/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 control

Terraform provider 支持 dashboard 的 access control 模型，允许你限制写入权限并设置 ownership：

resource "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 provider

elasticstack_kibana_dashboard 资源要求Elastic Stack 9.4 或更高版本，并可在最新版本的 Elastic Stack Terraform provider 中使用。

开始步骤如下：

  • 配置你的 provider，使其能够连接 Kibana：
terraform { required_providers { elasticstack = { source = "elastic/elasticstack" version = "~> 0.14" } } } provider "elasticstack" { kibana {} }
  • 使用上面的任意示例定义你的第一个 dashboard。
  • 运行terraform plan 来预览变更，然后运行 terraform apply 来创建资源。
  • 将已有dashboards 导入Terraform state：
terraform 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 Objective（SLO）以及 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

http://www.jsqmd.com/news/900923/

相关文章：

  • 2026年 哈尔滨国家开放大学报名指南：国开高起专/专升本热门专业与免试入学深度解析及学历价值推荐 - 品牌企业推荐师（官方）
  • HarmonyOS vibrator API 封装解析：DeviceUtil 振动工具函数从入门到实战
  • 用Unity Embedded Browser插件打造混合应用：本地HTML图表（ECharts）与Unity 3D场景实时交互实战
  • ChatGPT能听懂巴赫赋格吗？：实测12款提示词模板，3分钟生成专业级和声分析报告（附MIT音乐认知实验室验证数据）
  • SLANeXt_wireless_onnx深度解析：革新表格识别的终极AI模型
  • ChatGPT写诗总像说明书？——从古典格律到自由诗体的12种结构化提示模板（含平仄校验与意象密度优化公式）
  • 数据主权时代：如何构建个人AI记忆中心的完整技术方案
  • 如何用Arduino-ESP32快速构建智能物联网设备：从入门到实战的完整指南
  • HarmonyOS 屏幕信息获取入门：getDefaultDisplaySync 与 getAllDisplays 详解
  • 用CloudCompare和Python处理DublinCityDataSet点云数据，我踩过的那些坑（附完整代码）
  • ppf-contact-solver故障排除：安装依赖冲突的终极解决指南
  • AdelaiDepth深度解析：从单张图像重建3D场景的完整指南
  • E5-small常见问题解答：解决使用过程中的10个典型问题
  • 别再拍脑袋定样本量了！用Excel手把手教你搞定市场调研问卷的样本容量（附置信区间计算模板）
  • 如何永久保存微信聊天记录：WeChatMsg完整操作指南
  • AI优化建议：让AI帮你优化代码性能
  • 别再手动转IMU了！用MATLAB实现椭球拟合自动校准加速度计（附完整代码）
  • 从MLM到RTD：一文读懂DeBERTa V3的预训练任务革新与HuggingFace快速上手
  • 鸿蒙刘海屏、水滴屏、瀑布屏适配：用 DisplayUtil 获取不可用区域
  • 从PC到AI，联想中国一场必打的仗
  • 如何快速上手AdelaiDepth：5分钟实现单目深度估计 [特殊字符]
  • HarmonyOS FoldStatus 与 FoldDisplayMode 枚举深度解析：折叠屏开发不再难
  • 多家对比才知道!机闸一体式钢制闸门哪家好、哪家优惠?认准河北闸之都实体厂家，可定制，品质价格双保障 - 栗子测评
  • 10个免费VMware Workstation Pro 17许可证密钥：专业虚拟化快速激活指南
  • LightRAG 入门指南：手把手教你用图增强 RAG 系统
  • 别再死记硬背了！用COMSOL做场路耦合，搞懂‘外部U vs. I’和‘外部I vs. U’到底怎么选
  • 2026年移动岗亭十大品牌厂家推荐：不锈钢/铝合金/雕花板岗亭，小区/工地/景区/警务/收费多场景定制选购指南 - 品牌企业推荐师（官方）
  • 从理论到实践：MiniCPM5-1B-MLX架构设计与实现原理深度剖析
  • 智能体时代，AI支付会是下一个“二维码”吗？
  • Bat批处理进阶玩法：用ren命令批量重命名，实现‘去头掐尾’和‘中间替换’