Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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 desenvolvedor para duas realizações:

  • Docker Compose para o desenvolvimento local, e
  • a Recipe helm sintetizada que executa a imagem upstream oficial grafana/grafana diretamente no Kubernetes (sem chart externo).

A Recipe helm sintetizada é o caminho do Kubernetes: ela 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 por realização a camada de Recipe selecionada pelo Manifest. Mais dois Aggregates mostram o mesmo servidor com uma credencial opcional de senha de administrador vinculada: 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.

Arquivos

ArquivoPapel
aggregate.yamlIntenção do desenvolvedor: um componente dashboards do tipo core/observability/grafana, sem credencial — a conta de administrador usa a senha de desenvolvimento determinística da Recipe.
aggregate-auth.yamlO mesmo servidor com uma credencial de senha de administrador vinculada ao slot opcional admin_password do componente (caminho do Compose).
aggregate-helm-synth-auth.yamlO mesmo servidor com uma credencial referenciável vinculada para o caminho helm sintetizado — o valor é materializado como um Secret do Kubernetes que o Deployment referencia.
manifest-compose.yamlMapeia o tipo Grafana para a Recipe do Compose (compose/grafana) e a credencial para dotenv-secret.
manifest-helm-synth.yamlMapeia o tipo Grafana para a Recipe helm sintetizada (helm/grafana) e a credencial para k8s-secret-from-parameter.
release-compose.yaml / release-helm-synth.yamlDocumentos do operador para as duas realizações, sem credencial vinculada.
release-compose-auth.yaml / release-helm-synth-auth.yamlDocumentos do operador que habilitam a autenticação.

O que ele demonstra

  • Uma única superfície de autoria, muitos destinos. Um único Aggregate é a fonte da verdade sobre o que o stack é. Cada Manifest diz como realizá-lo.
  • Um servidor apoiado em um volume persistente. O Grafana mantém o seu estado — usuários, dashboards salvos, preferências — em disco, então 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 nomeado 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 provedor helm traduz em manifestos do Kubernetes sem nenhum chart externo. O conjunto de recursos renderizado é exatamente o que o Workload declara. Como o nome grafana é usado tanto por uma Recipe do Compose quanto por uma helm sintetizada, os Manifests as referenciam com escopo de provedor como compose/grafana e helm/grafana.
  • Uma senha de administrador determinística. A conta de administrador do Grafana está sempre presente. Este componente liga a senha por meio de um slot de credencial opcional admin_password: quando nenhuma credencial está vinculada (o Aggregate base), a Recipe define uma senha de desenvolvimento determinística, então a renderização é idêntica byte a byte entre execuções; quando uma credencial está vinculada, o valor injetado se torna a senha de administrador. No Compose ela aparece como a variável de ambiente GF_SECURITY_ADMIN_PASSWORD; no Kubernetes, o caminho helm sintetizado a materializa como um Secret que o Deployment referencia por meio de um secretKeyRef de ambiente, então o texto puro nunca aparece no manifesto do Deployment.

Não modelado aqui

O Grafana é implantado de forma independente. Ligar uma fonte de métricas ou de logs — por exemplo, um servidor Prometheus — ao Grafana como fonte de dados provisionada não está modelado: o componente não declara nenhum socket uses.

Gerar o exemplo

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example grafana-dashboards

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

Terminal window
cd grafana-dashboards

Build

Este workspace não traz nenhum .aggrega-config.yaml, então as entidades da biblioteca padrão são resolvidas a partir do registro do hub, hub.aggrega.ai, e nenhuma flag de catálogo é necessária; --auto-pull escreve durante o build o lockfile que falta a um clone novo:

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

Os artefatos renderizados ficam em dist/.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `grafana-dashboards`, chame uma vez a ferramenta `scaffold` com `example` definido como `grafana-dashboards` e sem `dir`: ela grava o exemplo em uma nova pasta `grafana-dashboards`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-compose.yaml`, `release-helm-synth.yaml`, `release-compose-auth.yaml`, `release-helm-synth-auth.yaml` — cada vez com `workspace_root` definido como `grafana-dashboards`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam 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 se torna 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 o referencia por meio de um secretKeyRef de ambiente vinculado a GF_SECURITY_ADMIN_PASSWORD. Por isso, a senha em texto puro nunca aparece no manifesto do Deployment — apenas no Secret.

O valor origin nos Aggregates autenticados é um espaço reservado de desenvolvimento; forneça um valor real por meio da sua fonte de credenciais em qualquer implantação real.

Executá-lo (Compose)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker compose -f dist/app/compose/docker-compose.yaml up -d

Abra http://localhost:3000 — a interface web do Grafana — e faça login como admin com a senha de desenvolvimento. Para desmontar, use docker compose -f dist/app/compose/docker-compose.yaml down.