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

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 exists

Trê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 componente db do tipo core/datastore/postgres, uma app que o usa através de uses, 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 anexo core/backup para 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:

Terminal window
aggrega scaffold --example postgres-three-realizations

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd postgres-three-realizations

Compilação

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega 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:

Terminal window
rm -rf dist && aggrega build --release release-managed.yaml

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

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

Gerido — 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.

dist/stack/helm/app-deployment.yaml
- 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.net

A Recipe publica esse nome como host em vez da referência do Terraform, e a aplicação recebe-o:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
variávelrelease-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

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:

dist/stack/helm/db-service.yaml
[… 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: 5432

Nenhum 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
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

Referenciar 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 of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

A comparação que é o essencial

O ambiente renderizado da aplicação, os três lado a lado:

variávelauto-alojadogeridoexterno
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

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.