Grafana — um Aggregate, dois destinos, credencial de administrador opcional
Este exemplo compila um único servidor de dashboards e visualização Grafana a partir de um único Aggregate escrito pelo programador em duas realizações:
- Docker Compose para o desenvolvimento local, e
- a Recipe helm sintetizada que executa a imagem upstream oficial
grafana/grafanadiretamente no Kubernetes (sem chart externo).
A Recipe helm sintetizada é o caminho do Kubernetes: depende apenas de uma tag de imagem oficial em vez de um chart de terceiros, e o seu conjunto de recursos renderizado é exatamente o que a carga de trabalho declara.
O mesmo aggregate.yaml conduz ambas. Só muda, de realização para realização, a camada de Recipe selecionada pelo Manifest. Mais dois Aggregates mostram o mesmo servidor com uma credencial opcional de palavra-passe de administrador anexada: aggregate-auth.yaml para o caminho do Compose (uma credencial inject-value exposta como variável de ambiente), e aggregate-helm-synth-auth.yaml para o caminho helm sintetizado (uma credencial referenciável materializada como um Secret do Kubernetes).
O servidor Grafana empacotado é AGPL-3.0.
Ficheiros
| Ficheiro | Papel |
|---|---|
aggregate.yaml | Intenção do programador: um componente dashboards do tipo core/observability/grafana, sem credencial — a conta de administrador usa a palavra-passe de desenvolvimento determinística da Recipe. |
aggregate-auth.yaml | O mesmo servidor com uma credencial de palavra-passe de administrador anexada ao slot opcional admin_password do componente (caminho do Compose). |
aggregate-helm-synth-auth.yaml | O mesmo servidor com uma credencial referenciável anexada para o caminho helm sintetizado — o valor é materializado como um Secret do Kubernetes que o Deployment referencia. |
manifest-compose.yaml | Mapeia o tipo Grafana para a Recipe do Compose (compose/grafana) e a credencial para dotenv-secret. |
manifest-helm-synth.yaml | Mapeia o tipo Grafana para a Recipe helm sintetizada (helm/grafana) e a credencial para k8s-secret-from-parameter. |
release-compose.yaml / release-helm-synth.yaml | Documentos do operador para as duas realizações, sem credencial anexada. |
release-compose-auth.yaml / release-helm-synth-auth.yaml | Documentos do operador que ativam a autenticação. |
O que demonstra
- Uma única superfície de autoria, muitos destinos. Um único Aggregate é a fonte de verdade sobre o que a stack é. Cada Manifest diz como realizá-la.
- Um servidor apoiado num volume persistente. O Grafana guarda o seu estado — utilizadores, dashboards guardados, preferências — em disco, pelo que o componente declara um volume de dados dimensionado a partir de
infra.storage. No Kubernetes, a Recipe helm sintetizada renderiza um Deployment com um PersistentVolumeClaim montado em/var/lib/grafana; no Compose, o serviço monta um volume com nome no mesmo caminho. - Síntese de Workload (Kubernetes). A Recipe helm sintetizada declara um Workload — um Deployment mais um Service ClusterIP que executa a imagem oficial
grafana/grafana— que o fornecedor helm traduz em manifestos do Kubernetes sem nenhum chart externo. O conjunto de recursos renderizado é exatamente o que o Workload declara. Como o nomegrafanaé usado tanto por uma Recipe do Compose como por uma helm sintetizada, os Manifests referenciam-nas com âmbito de fornecedor comocompose/grafanaehelm/grafana. - Uma palavra-passe de administrador determinística. A conta de administrador do Grafana está sempre presente. Este componente liga a palavra-passe através de um slot de credencial opcional
admin_password: quando nenhuma credencial está anexada (o Aggregate de base), a Recipe define uma palavra-passe de desenvolvimento determinística, pelo que a renderização é idêntica byte a byte entre execuções; quando uma credencial está anexada, o valor injetado torna-se a palavra-passe de administrador. No Compose surge como a variável de ambienteGF_SECURITY_ADMIN_PASSWORD; no Kubernetes, o caminho helm sintetizado materializa-a como um Secret que o Deployment referencia através de umsecretKeyRefde ambiente, pelo que o texto simples nunca aparece no manifesto do Deployment.
Não modelado aqui
O Grafana é implementado de forma autónoma. Ligar uma fonte de métricas ou de registos — por exemplo, um servidor Prometheus — ao Grafana como fonte de dados aprovisionada não está modelado: o componente não declara nenhum socket uses.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example grafana-dashboardsDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd grafana-dashboardsCompilação
Este workspace não contém nenhum .aggrega-config.yaml, pelo que as entidades da biblioteca standard são resolvidas a partir do registo do hub, hub.aggrega.ai, e não é necessária nenhuma flag de catálogo; --auto-pull escreve durante a compilação o lockfile que falta a um clone acabado de criar:
# 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-pullOs artefactos renderizados ficam em dist/.
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver uma pasta `grafana-dashboards`, chame uma vez a ferramenta `scaffold` com `example` definido como `grafana-dashboards` e sem `dir`: esta escreve o exemplo numa nova pasta `grafana-dashboards`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml`, `release-helm-synth-auth.yaml` — de cada vez com `workspace_root` definido como `grafana-dashboards`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros cada build escreveu; encontram-se em `grafana-dashboards/dist/`.Nota sobre a entrega da credencial
No caminho do Compose, a credencial é um segredo inject-value (aggregate-auth.yaml): o seu valor é entregue no pipe de ambiente do componente e torna-se a variável de ambiente do serviço GF_SECURITY_ADMIN_PASSWORD.
O caminho helm sintetizado usa uma credencial referenciável (aggregate-helm-synth-auth.yaml): o valor é materializado como um Secret do Kubernetes, e o Deployment referencia-o através de um secretKeyRef de ambiente ligado a GF_SECURITY_ADMIN_PASSWORD. Por isso, a palavra-passe em texto simples nunca aparece no manifesto do Deployment — apenas no Secret.
O valor origin nos Aggregates autenticados é um marcador de posição de desenvolvimento; forneça um valor real através da sua fonte de credenciais em qualquer implementação real.
Executá-lo (Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dAbra http://localhost:3000 — a interface web do Grafana — e inicie sessão como admin com a palavra-passe de desenvolvimento. Para desmontar, execute docker compose -f dist/app/compose/docker-compose.yaml down.