Stack Keycloak — um servidor de identidade apoiado em banco de dados composto como módulo
Este exemplo compila um stack pequeno e real — um servidor de identidade apoiado em banco de dados — para manifestos do Kubernetes sintetizados a partir de um único Aggregate escrito pelo desenvolvedor.
O servidor de identidade não é um único componente. É um módulo: um subagregado reutilizável que compõe dois componentes de carga de trabalho única —
- um servidor que serve o console da conta e os endpoints de tokens na sua porta HTTP e não mantém estado local, e
- um backend, PostgreSQL, que guarda os realms, os clientes e os usuários do servidor e os persiste em um volume.
O módulo liga a sua própria aresta interna do servidor ao backend e exporta o servidor como o seu endpoint público http. O Aggregate de nível mais alto importa o módulo pelo nome e renderiza o stack composto; o operador dimensiona os componentes internos do módulo na Release.
Arquivos
| Arquivo | Papel |
|---|---|
aggregate.yaml | Intenção do desenvolvedor: importa o módulo de servidor de identidade (core/keycloak). |
manifest-helm-synth.yaml | Mapeia os tipos servidor e backend para as suas Recipes helm synth, e a Feature de credencial que o módulo vincula, para a realização que emite um Secret a partir dos parâmetros de credencial do módulo. |
release-helm-synth.yaml | Documento do operador para o destino Kubernetes. Dimensiona os componentes internos do módulo pelos seus IDs com escopo de módulo; tudo o que fica com os valores padrão do esquema é renderizado de forma autônoma. |
O que ele demonstra
- Composição como módulo. Uma capacidade com várias cargas de trabalho — um servidor de identidade que na verdade é um servidor mais um banco de dados de configuração — é empacotada como um subagregado que compõe dois componentes de carga de trabalho única, não como um único componente monolítico. O módulo é importado pelo nome e reutilizado onde quer que um servidor de identidade seja necessário.
- Uma aresta interna dentro do módulo. O servidor declara um uso do backend; o host, a porta, o usuário e o banco de dados dos
providesda Recipe do backend são canalizados para o servidor e compostos na sua conexão com o banco de dados. O compilador roteia as strings sem interpretá-las. - Um endpoint público. O módulo exporta o seu servidor como
http, o nome público estável ao qual um consumidor se conecta — desacoplado dos nomes dos componentes internos do módulo. - Dimensionamento dos componentes internos pelo operador. A Release endereça os componentes internos do módulo pelos seus IDs com escopo de módulo (
server.backend,server.server) para definir os recursos de computação, sem que o Aggregate do desenvolvedor repita o dimensionamento físico. - Esquema com migração própria. Na inicialização, o servidor provisiona e migra o seu próprio esquema no backend, então ele inicia com um esquema pronto, sem nenhuma etapa de migração separada.
- Uma credencial compartilhada, obtida por referência. O servidor se autentica no seu backend PostgreSQL, então os dois compartilham uma única senha. O módulo a recebe como parâmetro,
db_password, e vincula com ela duas vezes a Feature de credencialcore/referenced-secret: ao slot de credencial do próprio backend, e comocredentialda conexão do servidor com o backend, a conexão na qual o servidor a apresenta. Cada carga de trabalho lê a senha de um Secret em vez de trazê-la inline; a senha da conta de administrador de bootstrap é um segundo parâmetro,admin_password. Como o módulo vincula essa Feature, o Manifest a mapeia. Este exemplo deixa os dois parâmetros nos valores padrão de desenvolvimento do módulo e mapeia a Feature parak8s-secret-from-parameter, que emite um Secret que traz cada valor, então o stack é executado de forma autônoma. Para uma Release que atende tráfego real, o Aggregate declara parâmetros próprios e os repassa para baixo por meio deaggregates.server.parameters, a Release os preenche, e o Manifest mapeia a Feature parak8s-existing-secret, que lê cada parâmetro como o nome de um Secret que já existe no namespace. - Imagens reproduzíveis. Tanto o servidor quanto o backend fixam tags de imagem explícitas, então os manifestos renderizados referenciam imagens estáveis.
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:
aggrega scaffold --example keycloak-stackEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd keycloak-stackBuild
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:
aggrega build --release release-helm-synth.yaml --auto-pullOs artefatos renderizados ficam em dist/. O destino Kubernetes renderiza manifestos simples offline — nenhum pull de chart é necessário.
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 você mesmo. Se a pasta do workspace ainda não contiver uma pasta `keycloak-stack`, chame a ferramenta `scaffold` uma vez com `example` definido como `keycloak-stack` e sem `dir`: ela grava o exemplo em uma nova pasta `keycloak-stack`. Depois chame a ferramenta `build` com `workspace_root` definido como `keycloak-stack`, `release` definido como `release-helm-synth.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `keycloak-stack/dist/`.Como fica o stack composto
O servidor é renderizado como um Deployment sem estado mais um Service ClusterIP na porta HTTP. O seu contêiner traz a conexão composta a partir da aresta para o backend — o nome do Service interno ao cluster do backend, o usuário e o banco de dados — além das configurações HTTP para execução autônoma, dos endpoints de health ativados e servidos na porta de gerenciamento, e da conta de administrador de bootstrap, com as duas senhas lidas de Secrets:
env: - name: KC_DB_PASSWORD valueFrom: secretKeyRef: name: server-zdserver-db.credential key: db-password - name: KC_BOOTSTRAP_ADMIN_PASSWORD valueFrom: secretKeyRef: name: server-zdserver-admin-password key: admin-password - name: KC_DB value: postgres - name: KC_DB_URL_HOST value: server-zdbackend-default - name: KC_DB_URL_PORT value: "5432" - name: KC_DB_URL_DATABASE value: keycloak - name: KC_DB_USERNAME value: keycloak - name: KC_HTTP_ENABLED value: "true" - name: KC_HOSTNAME_STRICT value: "false" - name: KC_HEALTH_ENABLED value: "true" - name: KC_HTTP_MANAGEMENT_PORT value: "9000" - name: KC_BOOTSTRAP_ADMIN_USERNAME value: adminO contêiner declara a porta de gerenciamento, 9000, ao lado da porta HTTP, e o Deployment testa o servidor ali: uma startup probe em /health/started segura as demais enquanto o servidor inicializa, uma readiness probe em /health/ready mantém o tráfego afastado até que ele responda, e uma liveness probe em /health/live o reinicia se ele parar. O Service continua encaminhando apenas a porta HTTP.
O backend é renderizado como um StatefulSet com um volume persistente montado em /var/lib/postgresql/data, mais um Service ClusterIP e um Service headless. O seu POSTGRES_PASSWORD lê a mesma senha do banco de dados de um Secret próprio, server-zdbackend-password. Os três Secrets são emitidos ao lado das cargas de trabalho, um por credencial que o módulo vincula, cada um trazendo o valor padrão de desenvolvimento do módulo.