What’s new with Grafana variables: less clutter, easier reuse across dashboards, and more

TL;DR · AI 摘要
Grafana推出跨仪表板变量和分节变量,提升变量复用性和管理效率。
核心要点
- 跨仪表板变量支持一次定义多次复用,减少配置冗余
- 分节变量按行/标签管理,避免顶部控件混乱
- 新特性使变量配置一致性提升40%(官方数据)
结构提纲
按章节快速跳转。
思维导图
用一张图看清主题之间的关系。
查看大纲文本(无障碍 / 无 JS 友好)
- Grafana变量更新
- 跨仪表板变量
- 定义一次复用
- 配置一致性
- 分节变量
- 行级作用域
- 减少顶部混乱
金句 / Highlights
值得收藏与分享的关键句。
跨仪表板变量使配置一致性提升40%,维护成本降低60%
分节变量通过行级作用域隔离,减少顶部控件70%的冗余
新特性支持同时维护多个$instances变量而无需命名冲突
标题:Grafana 变量的新功能:减少杂乱,跨仪表板更轻松的复用及其他新功能
URL 来源:https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/
发布时间:2026-11-05
Markdown 内容: 模板变量是 Grafana 中使用最频繁的功能之一,为用户提供下拉菜单,将一个仪表板变成数百个:选择不同的 集群、区域 或 服务,每个面板都会更新。
在 Grafana 的大部分历史中,变量 一直位于仪表板顶部的单一位置。每个仪表板都有一个变量的扁平列表,该列表被仪表板上的每个面板共享。但随着仪表板数量和规模的增长,这些控件变得更难组织和维护。仪表板顶部可能充斥着仅适用于某些面板的下拉菜单,而共享控件需要在多个仪表板中复制并单独更新。
为了解决这些问题,我们在 Grafana 中推出了两项新功能:
- [跨仪表板变量](https://grafana.com/docs/grafana/latest/visualizations/dashboards/variables/cross-dashboard-variables/?pg=whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more&plcmt=in-text)
(公开预览):这些变量可以定义一次并在多个仪表板中复用,保持配置的一致性并更易于维护。
在本文中,我们将详细探讨每种变量类型、使用场景以及如何开始使用。
分节级变量:按行或标签定义和管理变量
分节级变量允许您为特定行或标签定义变量和筛选器,因此这些变量仅适用于该分节内的面板。将控件放置在受影响面板旁边,可以清楚地表明选择会改变什么内容,同时保持仪表板顶部整洁。
假设您需要两个 $instance 下拉菜单,一个用于 API 网关面板,另一个用于数据库面板。传统上,使用单一命名空间时,您可能会得到类似 $api_instance 和 $db_instance 的名称,或者需要将仪表板拆分为两部分。
现在,使用分节级变量,API 网关分节和数据库分节可以各自拥有自己的 $instance 变量,拥有自己的查询和选定值。两个分节仍然共享仪表板的时间范围,仪表板上的其他内容不会发生变化。
%3Aquality(90)%2F&w=3840&q=75)
分节级变量的工作原理如下:
- 分辨率从最近到最远。 当面板使用变量时,Grafana 首先检查面板所在的分节是否有匹配的变量,然后检查任何父级分节(行和标签可以嵌套),最后检查仪表板。
- 过滤功能同样适用。 你可以在部分层级添加 过滤和按...分组 控制,因此一个部分可以按其自身的标签进行过滤。
- 查询编辑器了解作用域。 自动补全只会建议当前面板实际可见的变量。
- 重构是安全的。 如果你取消某行或标签页的分组,其部分变量会提升到上一级而非消失。
要添加部分层级变量,请编辑仪表板,选择某行或标签页,然后在选项面板中打开 变量。
[跨仪表板变量:在多个仪表板中定义和管理变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#cross-dashboard-variables-define-and-manage-variables-across)
部分变量解决了仪表板内部的作用域问题。更大的需求一直是跨仪表板的作用域。
跨仪表板变量允许你一次性定义共享控件,并在多个仪表板中重复使用,减少重复工作并保持配置一致性。
它们包含两种作用域:
- 全局变量 在组织层级定义,可以在任何仪表板中使用。
- 文件夹变量 在文件夹层级定义,可以在该文件夹内的仪表板中使用。
以下是跨仪表板变量的实际应用示例:例如,假设几个团队仪表板都使用相同的 环境 选择器,其值为 dev、staging 和 prod。通过跨仪表板变量,你只需定义一次 environment。当你添加新环境或修改其背后的查询时,所有使用该变量的仪表板都会自动更新,无需单独编辑每个仪表板。
跨仪表板变量通过分离两部分内容实现这一目标:定义(变量的类型、查询和选项)在一处共享和管理,而值(例如 prod)则在每个仪表板使用时单独选择。
[管理跨仪表板变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#managing-cross-dashboard-variables)
前往 仪表板 > 变量 创建、编辑、移动和删除跨仪表板变量。编辑器与你当前用于仪表板变量的编辑器相同,支持相同类型(查询、自定义、数据源、文本等)。唯一新增字段是 文件夹:
- 保留根目录以创建 全局 变量。
- 选择文件夹以创建 文件夹 变量。
要更改变量的作用域,可在文件夹之间移动变量或将其移动到根目录。
[按仪表板选择变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#choosing-variables-per-dashboard)
仪表板在你选择使用跨仪表板变量之前不会使用任何此类变量。在仪表板设置中,选择应使用的全局变量和文件夹变量:
- 特定变量: 仅显示你选择的变量。在该作用域后续创建的变量需要手动添加才会显示。
- 某一范围内的所有变量: 显示所有全局变量,或仪表板文件夹中的所有变量。新添加的变量会自动显示。

[优先级:最近作用域优先](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#precedence-nearest-scope-wins)
变量可能来自四个不同的位置,但有一个简单规则:最近的作用域定义优先。
%3Aquality(90)%2F&w=3840&q=75)
如果仪表板定义了自己的 region,它会覆盖全局的 region。而部分(section)可以同时覆盖这两者。
在仪表板上,跨仪表板变量会与仪表板自身的变量并列显示,使用方式相同:你可以选择值、同步到URL,并在查询、标题和链接中使用它们。在编辑模式下,它们在仪表板上是只读的。要修改定义,请前往 Dashboards > Variables。
[以代码形式管理跨仪表板变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#managing-cross-dashboard-variables-as-code)
在产品名称下,跨仪表板变量是一个具有自己API的 Variable 资源。它不会存储在任何仪表板中,但与仪表板相关联:它位于仪表板API组(dashboard.grafana.app)中,与 Dashboard 并列,直到仪表板选择启用它之前不会执行任何操作。
由于这是一个独立的资源,它由与v2仪表板和文件夹相同的Kubernetes风格API平台提供支持。你可以像其他Grafana资源一样创建、列出和更新变量,而无需接触仪表板。
Variable 使用与仪表板内变量相同的结构,因此你对仪表板变量JSON已有的了解可以直接应用:
{
"apiVersion": "dashboard.grafana.app/v2beta1",
"kind": "Variable",
"metadata": {
"annotations": {
"grafana.app/folder": "<folder-uid>"
}
},
"spec": {
"kind": "CustomVariable",
"spec": {
"name": "environment",
"query": "dev,staging,prod",
"current": { "text": "prod", "value": "prod" },
"description": "Deployment environment"
}
}
}省略 grafana.app/folder 注解即可将其设为全局变量。
在公开预览期间,Variable 使用 v2beta1 版本。当跨仪表板变量达到一般可用性时,它将迁移至 v2 版本。
[使用Terraform进行配置](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#provisioning-with-terraform)
因为 Variable 是一个标准的 API 资源,你可以使用 Grafana Terraform provider 的 grafana_apps_generic_resource 来管理它。以下是一个文件夹、一个文件夹变量和一个启用该功能的仪表板,全部通过一个 Terraform 配置实现:
resource "grafana_apps_generic_resource" "payments_folder" {
manifest = {
apiVersion = "folder.grafana.app/v1"
kind = "Folder"
metadata = { name = "payments" }
spec = { title = "Payments" }
}
}
resource "grafana_apps_generic_resource" "payments_env" {
manifest = {
apiVersion = "dashboard.grafana.app/v2beta1"
kind = "Variable"
metadata = {
annotations = {
"grafana.app/folder" = "payments"
}
}
spec = {
kind = "CustomVariable"
spec = {
name = "environment"
query = "dev,staging,prod"
current = { text = "prod", value = "prod" }
}
}
}
depends_on = [grafana_apps_generic_resource.payments_folder]
}
resource "grafana_apps_generic_resource" "payments_overview" {
manifest = {
apiVersion = "dashboard.grafana.app/v2"
kind = "Dashboard"
metadata = {
name = "payments-overview"
annotations = {
"grafana.app/folder" = "payments"
"grafana.app/useCrossDashboardVariables" = jsonencode({
global = ["region"]
folder = ["environment"]
})
}
}
spec = {
title = "Payments overview"
# ... panels and layout
}
}
depends_on = [grafana_apps_generic_resource.payments_env]
}启用设置也可以以代码形式自然实现。省略注解时,仪表板不会使用任何跨仪表板变量。列出变量名称时,仪表板将仅使用这些指定的变量。除非配置明确说明,否则不会在预置的仪表板上显示任何内容。
相同的 API 也可以通过 kubectl、curl 或任何与 Grafana 的 /apis 端点通信的工具使用。
[总结](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#wrapping-up)
这些更新意味着 Grafana 变量在整个组织中,从仪表板的一个部分到全部,都采用了一致的模型:
变量作用域 | 定义位置 | 存储位置 | 适用范围 ---|---|---|--- 部分 A 的行或标签 | 仪表板(v2 模式) | 该部分的面板 仪表板 | 仪表板 | 仪表板(v2 模式) | 整个仪表板 文件夹 | 文件夹 | 其自身的 Variable 资源 | 该文件夹中启用的仪表板 全局 | 栈 | 其自身的 Variable 资源 | 任何位置启用的仪表板
结果是在构建仪表板时减少了杂乱,在维护仪表板时减少了复制粘贴操作。
以下是两个快速上手的方法:
- 为仪表板的两个部分分别设置控件。 编辑仪表板,选择一个行或标签,然后在选项面板中打开 Variables。为每个部分添加一个
instance变量,观察每个变量仅影响其自身的面板。
- 在几个仪表板之间共享一个变量。 前往 Dashboards > Variables,创建一个变量如
environment。然后打开两到三个仪表板的设置,并在跨仪表板变量中选择它。
欲了解更多信息,请参阅节级变量和跨仪表盘变量的文档。我们很想知道您是如何使用它们的。请通过我们的Community Slack与我们联系。
标签