Um contrato, três realizações
Uma base de dados PostgreSQL e a aplicação que a lê, implementadas de três maneiras diferentes a partir de um único Aggregate inalterado: PostgreSQL a correr no cluster, PostgreSQL como instância gerida na cloud e um servidor PostgreSQL que já existia antes de esta Release ser implementada.
A lição é o que não muda. A aplicação nomeia, uma única vez, as chaves que quer da base de dados e como lhes chamar. Nunca fica a saber qual das três respondeu. O compilador também nunca fica a saber: lê as chaves que a Recipe selecionada publicou e encaminha as strings.
A única coisa que varia
.-- helm/postgres ---------- a StatefulSet in the cluster /core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform one Component \ one contract '- helm/postgres-external -- a server that already existsTrês Recipes implementam o mesmo Component. Cada uma publica as mesmas chaves provides — host, port, user, database, protocol e as chaves que indicam onde um scraper encontra as métricas da base de dados, vazias nas três. Qual delas é executada é uma única linha no Manifest.
Ficheiros
aggregate.yaml— a intenção do programador, e o mesmo documento para as três Releases: um componentedbdo tipocore/datastore/postgres, umaappque o usa através deuses, e as cinco chaves que a aplicação pede. Nada aqui nomeia um destino, uma cloud ou uma Recipe.manifest-selfhosted.yaml,manifest-managed.yaml,manifest-external.yaml— os mapeamentos de Ops. Cada um escolhe a sua realização em uma linha: a que Recipe se associa o tipo de componente PostgreSQL. O gerido associa também a Feature de cópia de segurança que as suas Releases anexam.release-selfhosted.yaml,release-managed.yaml,release-external.yaml— o dimensionamento do operador em cada Release: armazenamento e versão do motor para a que fica no cluster, armazenamento, HA e um anexocore/backuppara a gerida, e o endereço do servidor existente para a referenciada.release-managed-dns.yaml— a Release gerida mais uma vez, com o nome DNS que o operador dá à instância, de modo que a aplicação recebe um nome que consegue resolver.catalog/— o Component próprio da aplicação e a única Recipe que o renderiza. Tudo o que está do lado da base de dados vem da biblioteca standard sem modificações.
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 postgres-three-realizationsDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd postgres-three-realizationsCompilação
aggrega build --release release-selfhosted.yaml --auto-pullaggrega build --release release-managed.yaml --auto-pullaggrega build --release release-managed-dns.yaml --auto-pullaggrega build --release release-external.yaml --auto-pull--auto-pull escreve o ficheiro de bloqueio de cada Release na sua primeira compilação; as compilações seguintes não precisam da flag. Cada uma escreve em dist/, e uma compilação acrescenta os seus ficheiros em vez de limpar o que uma anterior deixou. Convém remover dist/ entre execuções para ler isoladamente a saída de uma realização:
rm -rf dist && aggrega build --release release-managed.yamlCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole-lhe este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa própria. Se a pasta Workspace ainda não contiver uma pasta `postgres-three-realizations`, chame uma vez a ferramenta `scaffold` com `example` definido como `postgres-three-realizations` e sem `dir`: esta escreve o exemplo numa nova pasta `postgres-three-realizations`. Em seguida, chame a ferramenta `build` uma vez para cada Release, por esta ordem — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` e `release-external.yaml` — de cada vez com `workspace_root` definido como `postgres-three-realizations`, `release` definido como esse ficheiro, `auto_pull` definido como true e `write` definido como true. Indique-me que ficheiros cada compilação escreveu; encontram-se em `postgres-three-realizations/dist/`.O que cada uma renderiza
Auto-alojado — a Release executa o servidor
helm/postgres sintetiza a base de dados no cluster: um StatefulSet, um Service ClusterIP e um Service headless. provides.host é o nome simples desse Service, pelo que a aplicação o alcança pelo DNS interno do cluster.
- name: DB_HOST value: db-defaultGerido — um fornecedor de cloud executa o servidor
terraform/postgres-rds emite um aws_db_instance como HCL do Terraform, e o dimensionamento ha e o anexo core/backup do operador são mapeados para as definições nativas da instância: o retention_days: 14 do anexo torna-se o backup_retention_period = 14 da instância. A aplicação continua a ser renderizada para Kubernetes: os dois lados desta Release encontram-se no contrato publicado da base de dados, não num destino partilhado.
- name: DB_HOST value: ${module.db.address}Esse valor não é um hostname, e nada nesta compilação o transforma num. O endereço de uma instância RDS não existe até a instância ser criada, pelo que não há nada que um compilador executado antecipadamente possa consultar. O que a Recipe publica é uma referência do Terraform a uma saída do próprio módulo da base de dados; o compilador canaliza-a pela aresta sem lhe tocar, a Recipe da aplicação recebe-a tal e qual, e ela é renderizada no manifesto do Kubernetes como os carateres literais mostrados acima. O contentor recebe esse texto.
DB_PORT é diferente: é renderizado como "5432", porque a Recipe define a porta da instância a partir da Release e publica esse mesmo valor, que é conhecido antes de qualquer coisa existir.
A ligação nativa entre dois componentes é algo que um destino faz dentro da sua própria saída, pelo que aqui não há nenhuma a fazer. As duas pontas desta aresta são renderizadas através de destinos diferentes — a base de dados em HCL do Terraform, a aplicação num manifesto do Kubernetes — e uma referência do Terraform só tem significado dentro de uma configuração do Terraform. Ao atravessar essa junção, o valor publicado é entregue como texto, como qualquer outra string. Um consumidor renderizado no Terraform como Recipe source:, na mesma configuração raiz que a base de dados, recebe a mesma referência como um dos argumentos do seu módulo, e aí o Terraform resolve-a.
Esta é a regra geral, e não um caso especial para RDS: tudo o que depende do estado de um sistema em execução é expresso como um ponteiro determinístico que o runtime resolve, nunca como um valor que o compilador obtém. O papel do compilador é entregar o ponteiro inalterado. Fazer com que ele se resolva onde chega cabe ao autor da Recipe: publicar um endereço que o lado consumidor possa usar, ou dar aos dois componentes Recipes que renderizem no mesmo destino.
Dar à instância um nome que a aplicação consiga resolver
terraform/postgres-rds aceita a primeira delas como uma opção que o operador define. release-managed-dns.yaml é a Release gerida com um acréscimo, o nome DNS que o operador dá à instância:
db: infra: overrides: host: db.internal.example.netA Recipe publica esse nome como host em vez da referência do Terraform, e a aplicação recebe-o:
- name: DB_HOST value: db.internal.example.net| variável | release-managed.yaml | release-managed-dns.yaml |
|---|---|---|
DB_HOST | ${module.db.address} | db.internal.example.net |
DB_PORT | 5432 | 5432 |
Essa é a única linha da saída que muda. A Recipe não emite nenhum registo DNS nem nenhum alias para o nome, e a compilação não o resolve: o compilador canaliza-o exatamente como canalizou a referência. Fazer db.internal.example.net apontar para a instância quando ela existir — um registo na própria zona DNS do operador, dirigido ao endereço da instância — cabe ao operador, fora da Release. A chave é a mesma que a realização referenciada mais abaixo lê para o mesmo endereço; esta Recipe aceita-a como um nome simples ou um literal IP, e um valor que contenha um esquema, um caminho, um utilizador ou uma porta interrompe a compilação, já que a porta é o infra.port da Release e um consumidor compõe a sua ligação a partir dos dois.
Um consumidor renderizado na mesma configuração do Terraform que a base de dados também recebe o nome, e com ele perde a ordenação que a referência lhe dava: o Terraform atua sobre um módulo depois de um módulo que ele referencia, e um nome não referencia nada. Colocar esse consumidor numa fronteira própria que partilhe o directory: da base de dados e contenha um syncWave: posterior restabelece a ordem.
Externo — ninguém nesta Release executa o servidor
helm/postgres-external não aprovisiona absolutamente nada. Toda a sua saída é um Service que mapeia um nome interno do cluster para o endereço que a Release fornece:
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]spec: type: ExternalName externalName: postgres.data.example.net ports: - port: 5432Nenhum StatefulSet, nenhum volume, nenhum contentor — o ciclo de vida do servidor fica inteiramente fora desta Release. O endereço vem da Release:
db: infra: overrides: host: postgres.data.example.net- name: DB_HOST value: postgres.data.example.netReferenciar um servidor não é o mesmo que assumir o controlo dele. Esta Recipe alcança um servidor que continua a ser de propriedade externa; nada aqui o coloca sob a gestão da Release, e nada aqui o vai alterar.
Se o endereço for omitido, a compilação para e indica-o. Um servidor referenciado tem um endereço ou não tem nada, pelo que a Recipe recusa em vez de emitir um Service que sirva de alias a um nome vazio:
[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]assertion failed: the Manifest selects the referenced realization ofPostgreSQL, which addresses a server it does not provision, but no address wassupplied: set infra.overrides.host on this component in the Release to the DNSname or IP literal the existing server answers onA comparação que é o essencial
O ambiente renderizado da aplicação, os três lado a lado:
| variável | auto-alojado | gerido | externo |
|---|---|---|---|
POOL_SIZE | 10 | 10 | 10 |
DB_HOST | db-default | ${module.db.address} | postgres.data.example.net |
DB_NAME | appdb | appdb | appdb |
DB_PORT | 5432 | 5432 | 5432 |
DB_PROTOCOL | postgres | postgres | postgres |
DB_USER | appuser | appuser | appuser |
Mesmas variáveis, mesma ordem, sempre. Só muda a string por trás de uma delas. A Recipe da aplicação não nomeia nenhuma das variáveis DB_: emite o que quer que a aresta uses tenha resolvido, e é por isso que uma única Recipe é renderizada inalterada contra as três bases de dados.
E o compilador não sabe o que essas strings são. db-default é um nome de Service do Kubernetes, ${module.db.address} é uma referência do Terraform, postgres.data.example.net é um nome DNS — para o compilador são três strings que uma Recipe publicou sob a chave host e que uma aresta pediu para serem entregues como DB_HOST. Não verifica se alguma delas é encaminhável, nem se uma porta é um número, nem se um componente chamado db é uma base de dados. Associou a aresta pela etiqueta que o Component contém, leu a chave que o contrato declara e moveu o texto.
Onde fica a costura
Cada uma das três Releases foi escolhida por um mapeamento de Ops, e o documento do programador não foi tocado por essa escolha. Essa é a separação que o exemplo inteiro existe para tornar concreta:
- o programador diz de que a aplicação precisa de uma base de dados;
- Ops diz de que é feita uma base de dados — uma Recipe por realização;
- o operador diz qual delas esta Release recebe, e dimensiona-a.
Acrescente-se amanhã uma quarta realização — outra cloud, outro operador, um serviço do Compose para o trabalho local — e trata-se de mais uma Recipe a publicar as mesmas chaves, mais uma linha de Manifest. O aggregate.yaml neste diretório não muda.