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

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

ArquivoPapel
aggregate.yamlIntenção do desenvolvedor: importa o módulo de servidor de identidade (core/keycloak).
manifest-helm-synth.yamlMapeia 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.yamlDocumento 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 provides da 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 credencial core/referenced-secret: ao slot de credencial do próprio backend, e como credential da 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 para k8s-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 de aggregates.server.parameters, a Release os preenche, e o Manifest mapeia a Feature para k8s-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:

Terminal window
aggrega scaffold --example keycloak-stack

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

Terminal window
cd keycloak-stack

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
aggrega build --release release-helm-synth.yaml --auto-pull

Os 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: admin

O 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.