Grafana — un Aggregate, dos destinos, credencial de administrador opcional
Este ejemplo compila un único servidor de paneles y visualización Grafana a partir de un único Aggregate escrito por el desarrollador a dos realizaciones:
- Docker Compose para el desarrollo local, y
- la Recipe helm sintetizada que ejecuta la imagen upstream oficial
grafana/grafanadirectamente en Kubernetes (sin chart externo).
La Recipe helm sintetizada es la ruta de Kubernetes: depende solo de un tag de imagen oficial en lugar de un chart de terceros, y su conjunto de recursos renderizado es exactamente lo que declara la carga de trabajo.
El mismo aggregate.yaml impulsa ambas. Solo cambia por realización la capa de Recipe que selecciona el Manifest. Otros dos Aggregates muestran el mismo servidor con una credencial opcional de contraseña de administrador vinculada: aggregate-auth.yaml para la ruta de Compose (una credencial inject-value expuesta como variable de entorno), y aggregate-helm-synth-auth.yaml para la ruta helm sintetizada (una credencial referenciable materializada como un Secret de Kubernetes).
El servidor Grafana empaquetado tiene licencia AGPL-3.0.
Archivos
| Archivo | Rol |
|---|---|
aggregate.yaml | Intención del desarrollador: un componente dashboards de tipo core/observability/grafana, sin credencial — la cuenta de administrador usa la contraseña de desarrollo determinista de la Recipe. |
aggregate-auth.yaml | El mismo servidor con una credencial de contraseña de administrador vinculada al slot opcional admin_password del componente (ruta de Compose). |
aggregate-helm-synth-auth.yaml | El mismo servidor con una credencial referenciable vinculada para la ruta helm sintetizada — el valor se materializa como un Secret de Kubernetes al que hace referencia el Deployment. |
manifest-compose.yaml | Asigna el tipo Grafana a la Recipe de Compose (compose/grafana) y la credencial a dotenv-secret. |
manifest-helm-synth.yaml | Asigna el tipo Grafana a la Recipe helm sintetizada (helm/grafana) y la credencial a k8s-secret-from-parameter. |
release-compose.yaml / release-helm-synth.yaml | Documentos del operador para las dos realizaciones, sin credencial vinculada. |
release-compose-auth.yaml / release-helm-synth-auth.yaml | Documentos del operador que habilitan la autenticación. |
Lo que demuestra
- Una única superficie de autoría, muchos destinos. Un único Aggregate es la fuente de verdad sobre qué es el stack. Cada Manifest dice cómo realizarlo.
- Un servidor respaldado por un volumen persistente. Grafana guarda su estado — usuarios, paneles guardados, preferencias — en disco, así que el componente declara un volumen de datos dimensionado a partir de
infra.storage. En Kubernetes la Recipe helm sintetizada renderiza un Deployment con un PersistentVolumeClaim montado en/var/lib/grafana; en Compose el servicio monta un volumen con nombre en la misma ruta. - Síntesis de Workload (Kubernetes). La Recipe helm sintetizada declara un Workload — un Deployment más un Service ClusterIP que ejecuta la imagen oficial
grafana/grafana— que el proveedor helm traduce a manifiestos de Kubernetes sin ningún chart externo. El conjunto de recursos renderizado es exactamente lo que declara el Workload. Como el nombregrafanalo llevan tanto una Recipe de Compose como una helm sintetizada, los Manifests las referencian con ámbito de proveedor comocompose/grafanayhelm/grafana. - Una contraseña de administrador determinista. La cuenta de administrador de Grafana siempre está presente. Este componente conecta la contraseña a través de un slot de credencial opcional
admin_password: cuando no hay ninguna credencial vinculada (el Aggregate base) la Recipe establece una contraseña de desarrollo determinista, así que el renderizado es idéntico byte a byte entre ejecuciones; cuando hay una credencial vinculada, el valor inyectado se convierte en la contraseña de administrador. En Compose aparece como la variable de entornoGF_SECURITY_ADMIN_PASSWORD; en Kubernetes la ruta helm sintetizada la materializa como un Secret al que el Deployment hace referencia mediante unsecretKeyRefde entorno, así que el texto plano nunca aparece en el manifiesto del Deployment.
No modelado aquí
Grafana se despliega de forma independiente. La conexión de una fuente de métricas o de logs — por ejemplo un servidor Prometheus — a Grafana como fuente de datos aprovisionada no está modelada: el componente no declara ningún socket uses.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example grafana-dashboardsDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd grafana-dashboardsCompilación
Este workspace no lleva ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no se necesita ningún flag de catálogo; --auto-pull escribe durante la compilación el lockfile que le falta a un clon recién creado:
# 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-pullLos artefactos renderizados quedan en dist/.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `grafana-dashboards`, llama una vez a la herramienta `scaffold` con `example` establecido en `grafana-dashboards` y sin `dir`: escribe el ejemplo en una nueva carpeta `grafana-dashboards`. Después llama a la herramienta `build` una vez por cada Release, en este orden — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml`, `release-helm-synth-auth.yaml` — cada vez con `workspace_root` establecido en `grafana-dashboards`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `grafana-dashboards/dist/`.Nota sobre la entrega de credenciales
En la ruta de Compose la credencial es un secreto inject-value (aggregate-auth.yaml): su valor se entrega por la tubería de entorno del componente y se convierte en la variable de entorno del servicio GF_SECURITY_ADMIN_PASSWORD.
La ruta helm sintetizada usa una credencial referenciable (aggregate-helm-synth-auth.yaml): el valor se materializa como un Secret de Kubernetes, y el Deployment hace referencia a él mediante un secretKeyRef de entorno vinculado a GF_SECURITY_ADMIN_PASSWORD. Por tanto, la contraseña en texto plano nunca aparece en el manifiesto del Deployment — solo en el Secret.
El valor origin de los Aggregates autenticados es un marcador de posición de desarrollo; proporciona un valor real a través de tu fuente de credenciales para cualquier despliegue real.
Ejecutarlo (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dAbre http://localhost:3000 — la interfaz web de Grafana — e inicia sesión como admin con la contraseña de desarrollo. Para desmontarlo, usa docker compose -f dist/app/compose/docker-compose.yaml down.