跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

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 通过 env secretKeyRef 引用它,因此明文永远不会出现在 Deployment 清单中。

此处未建模的内容

Grafana 以独立方式部署。将指标或日志源(例如 Prometheus 服务器)作为预配置的数据源接入 Grafana 的做法未被建模:该组件没有声明 uses 插槽。

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example grafana-dashboards

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd grafana-dashboards

构建

此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:

Terminal window
# Local development (Docker Compose), development admin password
aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image), development admin password
aggrega build --release release-helm-synth.yaml --auto-pull
# The same realizations with authentication enabled
aggrega build --release release-compose-auth.yaml --auto-pull
aggrega 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)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker 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 拆除。