Stack Keycloak — um servidor de identidade apoiado numa base de dados composto como módulo
Este exemplo compila uma stack pequena e real — um servidor de identidade apoiado numa base de dados — em manifestos do Kubernetes sintetizados a partir de um único Aggregate escrito pelo programador.
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 a consola da conta e os endpoints de tokens na sua porta HTTP e não guarda estado local, e
- um backend, PostgreSQL, que guarda os realms, os clientes e os utilizadores do servidor e os persiste num 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 superior importa o módulo pelo nome e renderiza a stack composta; o operador dimensiona os componentes internos do módulo na Release.
Ficheiros
| Ficheiro | Papel |
|---|---|
aggregate.yaml | Intenção do programador: 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 anexa, 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 âmbito de módulo; tudo o que fica com as predefinições do esquema é renderizado de forma autónoma. |
O que demonstra
- Composição como módulo. Uma capacidade com várias cargas de trabalho — um servidor de identidade que na realidade é um servidor mais uma base de dados de configuração — é empacotada como um subagregado que compõe dois componentes de carga de trabalho única, e não como um único componente monolítico. O módulo é importado pelo nome e reutilizado onde quer que seja necessário um servidor de identidade.
- Uma aresta interna dentro do módulo. O servidor declara um uso do backend; o host, a porta, o utilizador e a base de dados dos
providesda Recipe do backend são encaminhados para o servidor e compostos na sua ligação à base de dados. O compilador encaminha as strings sem as interpretar. - Um endpoint público. O módulo exporta o seu servidor como
http, o nome público estável ao qual um consumidor se liga — 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 âmbito de módulo (
server.backend,server.server) para definir os recursos de computação, sem que o Aggregate do programador repita o dimensionamento físico. - Esquema com migração própria. No arranque, o servidor aprovisiona e migra o seu próprio esquema no backend, pelo que arranca com um esquema pronto, sem nenhum passo de migração separado.
- Uma credencial partilhada, obtida por referência. O servidor autentica-se no seu backend PostgreSQL, pelo que os dois partilham uma única palavra-passe. O módulo recebe-a como parâmetro,
db_password, e anexa com ela duas vezes a Feature de credencialcore/referenced-secret: ao slot de credencial do próprio backend, e comocredentialda ligação do servidor ao backend, a ligação na qual o servidor a apresenta. Cada carga de trabalho lê a palavra-passe a partir de um Secret em vez de a conter inline; a palavra-passe da conta de administrador de arranque é um segundo parâmetro,admin_password. Como o módulo anexa essa Feature, o Manifest mapeia-a. Este exemplo deixa os dois parâmetros nos valores predefinidos de desenvolvimento do módulo e mapeia a Feature parak8s-secret-from-parameter, que emite um Secret com cada valor, pelo que a stack é executada de forma autónoma. Para uma Release que serve tráfego real, o Aggregate declara parâmetros próprios e passa-os para baixo através deaggregates.server.parameters, a Release satisfá-los, 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 como o backend fixam tags de imagem explícitas, pelo que os manifestos renderizados referenciam imagens estáveis.
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 keycloak-stackDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd keycloak-stackCompilaçã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:
aggrega build --release release-helm-synth.yaml --auto-pullOs artefactos renderizados ficam em dist/. O destino Kubernetes renderiza manifestos simples offline — não é necessário nenhum pull de chart.
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 conta própria. Se a pasta da área de trabalho ainda não contiver uma pasta `keycloak-stack`, chame uma vez a ferramenta `scaffold` com `example` definido como `keycloak-stack` e sem `dir`: esta escreve o exemplo numa nova pasta `keycloak-stack`. Em seguida, 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. Indique quais os ficheiros que a compilação escreveu; encontram-se em `keycloak-stack/dist/`.Como é a stack composta
O servidor é renderizado como um Deployment sem estado mais um Service ClusterIP na porta HTTP. O seu contentor contém a ligação composta a partir da aresta para o backend — o nome do Service interno ao cluster do backend, o utilizador e a base de dados — além das definições HTTP para execução autónoma, dos endpoints de health ativados e servidos na porta de gestão, e da conta de administrador de arranque, com as duas palavras-passe lidas a partir 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 contentor declara a porta de gestão, 9000, ao lado da porta HTTP, e o Deployment verifica o servidor aí: uma startup probe em /health/started retém as restantes enquanto o servidor arranca, uma readiness probe em /health/ready mantém o tráfego afastado até que responda, e uma liveness probe em /health/live reinicia-o se parar. O Service continua a encaminhar 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 palavra-passe da base de dados a partir de um Secret próprio, server-zdbackend-password. Os três Secrets são emitidos ao lado das cargas de trabalho, um por cada credencial que o módulo anexa, cada um com o valor predefinido de desenvolvimento do módulo.