Kibana Dashboards API：适用于所有面板类型的稳定接口，在正式发布前经过 50 多个团队验证

作者：来自 Elastic Teresa Alvarez Soler

以代码管理 Kibana 仪表板：将仪表板提交到 Git，在不同环境之间进行推广，并通过 Kibana API 和 Terraform 自动化部署。

Kibana Dashboards API 和 Visualizations API 已在 Elastic 9.5 中达到生产就绪状态，并在所有订阅层级中提供，同时保持完全的向后兼容性。你可以将仪表板定义为 JSON，提交到 Git，然后使用 持续集成 /持续部署（CI/CD）流水线、Terraform 或任何你现有的工具，在不同环境之间进行部署。在 9.4 技术预览期间，已有超过 50 个团队测试了该 API，其中一些团队已经将其用于生产环境。9.5 还新增了 Tags 的独立 API（技术预览），而 Markdown 和 Links 面板 API 已在 Elastic Cloud Serverless 中提供，并将于 9.6 发布。

Kibana Dashboards API 的向后兼容性意味着什么

在技术预览期间，API 的结构可能会随着版本发生变化。\^1 如今情况已经不同。正式发布（GA）意味着：

• 完全向后兼容。 随着时间推移，会增加新的字段和面板类型，但现有字段和行为保持不变。任何未来的破坏性变更都会经过非常谨慎的评估，并且只会在新的主版本中引入。

• 生产就绪并提供完整支持。 该 API 享有 Elastic 的完整支持保障。你可以放心地将其用于生产环境中的自动化部署、环境推广以及程序化仪表板管理。

用于 Tags、Markdown 和 Links 面板的新 Kibana API

Elastic 9.5 还引入了一个新的 Tags 独立 API，用于对仪表板进行分 类 和筛选。

现在，你可以通过专用的 CRUD API 以编程方式管理 Tags，从而更轻松地在不同环境中大规模组织仪表板。

Markdown 和 Links 面板 API 已在 Elastic Cloud Serverless 中提供，并将于下一版本 Elastic Stack（9.6）中发布。

Kibana Dashboards API 支持哪些面板类型？

Dashboards API 在 9.5 中支持所有 by-value 面板（即直接定义在仪表板中的面板，而不是保存在 Library 中供复用的面板）。

每一种受支持的面板类型都拥有类型化（typed）且经过校验（validated）的 Schema。

面板类型	支持状态
XY 图表	支持
指标（Metrics）	支持
饼图（Pie）	支持
仪表盘（Gauge）	支持
热力图（Heatmap）	支持
数据表（Data tables）	支持
矩形树图（Treemap）	支持
Discover 会话	支持
Controls	支持
Markdown	支持
Links	支持
ML 面板	支持
Observability 面板	支持
Maps	即将推出
Vega	即将推出

如何以代码方式管理 Kibana 仪表板

Dashboards API 支持完整的"仪表板即代码（Dashboards as Code）"工作流：

• 将仪表板导出为结构清晰、便于比较差异的 JSON；

• 提交到 Git，作为唯一可信来源（source of truth）；

• 在 Pull Request 中审查变更；

• 将同一份定义部署到开发、测试和生产环境。

当仪表板开始以代码方式管理后，应将 Git 作为唯一可信来源。任何直接在 UI 中进行的修改，都会在下一次部署时被覆盖。

将仪表板迁移到不同 Space、集群或环境时，最大的挑战在于仪表板会引用数据视图（Data View）和 Library 可视化 对象等资源，而这些对象都是通过 ID 引用的。

由于这些 ID 是自动生成的，并且不同环境中的 ID 并不相同，因此，从一个环境导出的仪表板可能会引用另一个环境中不存在的对象。

下面列出了三种解决方式，按照自动化程度从高到低排序：

• 使用 Terraform。 Elastic Stack Terraform Provider 会跟踪每个资源，并自动维护各环境之间的 ID 映射，因此当你将仪表板从开发环境推广到生产环境时，引用关系能够保持一致。

• 使用 by-value 的 ES|QL 面板。 构建面板最具可移植性的方式，是直接在仪表板中使用 ES|QL 定义可视化。ES|QL 查询直接读取其中指定的索引，因此面板不会依赖 Data View 或 Library 对象。最终得到的是一个完全自包含、可移植的仪表板。

• 使用一致的 ID。 如果需要引用保存对象（例如 Data View 或 Library 可视化），应使用 PUT（upsert）而不是 POST（自动生成 ID）创建这些对象，并指定固定 ID。建议使用具有可读性的 ID，例如 logs-prod，这样便于在不同环境中复用和识别。

有关这些可移植性模式以及完整"仪表板即代码"工作流的详细介绍，请参阅 Manage dashboards as code 文档。

使用 Dashboards API 的 PUT 创建 Kibana 仪表板

下面是一个简单示例，使用 PUT（而不是 POST）创建一个包含指标面板的仪表板，并使用仪表板名称 service-health-overview 作为自定义 ID。

同样的方法也适用于创建保存在 Library 中的独立可视化对象。

`

1.  PUT kbn:/api/dashboards/service-health-overview
2.  {
3.    "title": "Service health overview",
4.    "description": "Key service metrics --- managed via API",
5.    "tags": [
6.      "production",
7.      "sre-team"
8.    ],
9.    "panels": [
10.      {
11.        "type": "vis",
12.        "grid": {
13.          "x": 0,
14.          "y": 0,
15.          "w": 12,
16.          "h": 8
17.        },
18.        "config": {
19.          "title": "Error rate (5xx)",
20.          "type": "metric",
21.          "data_source": {
22.            "type": "esql",
23.            "query": "FROM logs-* | WHERE http.response.status_code >= 500 | STATS error_rate=count(*) BY host.name"
24.          },
25.          "metrics": [
26.            {
27.              "type": "primary",
28.              "column": "count"
29.            }
30.          ]
31.        }
32.      }
33.    ]
34.  }

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

Kibana Dashboards API 路线图：Maps、Vega 和独立 API

我们正在持续扩展 API 的覆盖范围。

下一步将支持 Maps 和 Vega 面板，为它们提供类型化 Schema。

同时，我们还在构建 Discover 会话（不仅作为仪表板面板）、Vega、Maps 以及 Annotations 的独立 CRUD API，使它们能够独立于仪表板生命周期进行管理。

完整的 Schema 定义请参阅 Dashboards API 文档。

对于 Terraform 用户，Elastic Stack Terraform Provider 已支持正式发布的 Dashboards API。

注意

核心 API 与技术预览版本保持一致。

如果你已经基于 9.4 开发了相关集成，它们可以直接在 9.5 中继续使用。

唯一的破坏性变更只有两项较小调整，分别影响仪表板列表接口以及持续时间（duration）单位格式，详细信息请参阅相关文档。

原文：Manage Kibana dashboards as code with a stable API | Elasticsearch Labs