Grafana — 一个 Aggregate,两个目标,可选的管理员凭据
本示例将一个由开发者编写的 Aggregate 中的单个 Grafana 仪表板与可视化服务器编译为两种实现:
- 用于本地开发的 Docker Compose,以及
- 合成的 helm Recipe,直接在 Kubernetes 上运行官方上游
grafana/grafana镜像(不使用外部 chart)。
合成的 helm Recipe 是 Kubernetes 路径:它只依赖官方镜像标签, 而非第三方 chart,其渲染出的资源 集合与 workload 声明的内容完全一致。
同一个 aggregate.yaml 驱动两者。每种实现之间只有 Manifest 选择的
Recipe 层不同。另外两个 Aggregates 展示了附加可选管理员密码凭据的同一服务器:aggregate-auth.yaml 用于
Compose 路径(以环境变量形式呈现的 inject-value 凭据),
aggregate-helm-synth-auth.yaml 用于合成的 helm 路径(
物化为 Kubernetes Secret 的可引用凭据)。
打包的 Grafana 服务器采用 AGPL-3.0 许可。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | 开发者意图:一个类型为 core/observability/grafana 的 dashboards 组件,无凭据——管理员账户使用该 Recipe 的确定性开发密码。 |
aggregate-auth.yaml | 同一服务器,在组件的可选 admin_password 槽位上附加了管理员密码凭据(Compose 路径)。 |
aggregate-helm-synth-auth.yaml | 同一服务器,为合成的 helm 路径附加了可引用凭据——该值被物化为 Deployment 所引用的 Kubernetes Secret。 |
manifest-compose.yaml | 将 Grafana 类型映射到 Compose Recipe(compose/grafana),并将凭据映射到 dotenv-secret。 |
manifest-helm-synth.yaml | 将 Grafana 类型映射到合成的 helm Recipe(helm/grafana),并将凭据映射到 k8s-secret-from-parameter。 |
release-compose.yaml / release-helm-synth.yaml | 两种实现的运维记录,未附加凭据。 |
release-compose-auth.yaml / release-helm-synth-auth.yaml | 启用身份验证的运维记录。 |
演示内容
- 一个编写界面,多个目标。 单个 Aggregate 是栈是什么的 唯一事实来源。每个 Manifest 说明如何实现它。
- 由持久卷支撑的服务器。 Grafana 将其状态——用户、
已保存的仪表板、偏好设置——保存在磁盘上,因此该组件声明了一个
大小取自
infra.storage的数据卷。在 Kubernetes 上,合成的 helm Recipe 渲染一个 Deployment,并将 PersistentVolumeClaim 挂载到/var/lib/grafana;在 Compose 上,服务将命名卷挂载到同一 路径。 - Workload 合成(Kubernetes)。 合成的 helm Recipe 声明一个
Workload——一个 Deployment 加一个 ClusterIP Service,运行官方
grafana/grafana镜像——helm provider 将其转换为 Kubernetes 清单,无需外部 chart。渲染出的资源集合与 该 Workload 声明的内容完全一致。由于 Compose Recipe 和合成的 helm Recipe 都名为grafana,Manifests 以 provider 作用域的方式引用它们,即compose/grafana和helm/grafana。 - 确定性的管理员密码。 Grafana 管理员账户始终
存在。该组件通过可选的
admin_password凭据槽位传递密码:未附加凭据时(基础 Aggregate),Recipe 设置一个确定性的开发密码,使渲染结果 在多次运行间逐字节一致;附加凭据时,注入的 值成为管理员密码。在 Compose 上,它以GF_SECURITY_ADMIN_PASSWORD环境变量呈现;在 Kubernetes 上, 合成的 helm 路径将其物化为 Secret,Deployment 通过 envsecretKeyRef引用它,因此明文永远不会出现在 Deployment 清单中。
此处未建模的内容
Grafana 以独立方式部署。将指标或日志源(例如 Prometheus 服务器)作为预配置的数据源接入 Grafana 的做法未被建模:该组件没有声明 uses 插槽。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example grafana-dashboards然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd grafana-dashboards构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:
# Local development (Docker Compose), development admin passwordaggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image), development admin passwordaggrega build --release release-helm-synth.yaml --auto-pull
# The same realizations with authentication enabledaggrega build --release release-compose-auth.yaml --auto-pullaggrega build --release release-helm-synth-auth.yaml --auto-pull渲染产物位于 dist/ 下。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `grafana-dashboards` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `grafana-dashboards`,且不设置 `dir`:它会把示例写入新的 `grafana-dashboards` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具 — `release-compose.yaml`、`release-helm-synth.yaml`、`release-compose-auth.yaml`、`release-helm-synth-auth.yaml` — 每次都将 `workspace_root` 设为 `grafana-dashboards`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `grafana-dashboards/dist/` 下。凭据传递说明
在 Compose 路径上,凭据是 inject-value secret
(aggregate-auth.yaml):其值通过组件的环境
管道传递,并成为 GF_SECURITY_ADMIN_PASSWORD 服务环境变量。
合成的 helm 路径使用可引用凭据
(aggregate-helm-synth-auth.yaml):该值被物化为 Kubernetes
Secret,Deployment 通过绑定到
GF_SECURITY_ADMIN_PASSWORD 的 env secretKeyRef 引用它。因此明文密码永远不会出现在
Deployment 清单中——只出现在 Secret 中。
带身份验证的 Aggregates 中的 origin 值是开发用占位符;
任何真实部署都应通过你的凭据源提供真实值。
运行(Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -d打开 http://localhost:3000(Grafana Web 界面),以 admin 身份
使用开发密码登录。使用
docker compose -f dist/app/compose/docker-compose.yaml down 拆除。