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

Um contrato, três realizações

Um banco de dados PostgreSQL e a aplicação que o lê, implantados de três maneiras diferentes a partir de um único Aggregate inalterado: PostgreSQL rodando no cluster, PostgreSQL como instância gerenciada na nuvem e um servidor PostgreSQL que já existia antes de esta Release ser implantada.

A lição é o que não muda. A aplicação nomeia, uma única vez, as chaves que quer do banco de dados e como chamá-las. Ela nunca sabe qual das três respondeu. O compilador também nunca sabe: ele 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 dizem onde um scraper encontra as métricas do banco de dados, vazias nas três. Qual delas é executada é uma única linha no Manifest.

Arquivos

  • aggregate.yaml — a intenção do desenvolvedor, e o mesmo documento para as três Releases: um componente db do tipo core/datastore/postgres, um app que o usa por meio de uses, e as cinco chaves que a aplicação pede. Nada aqui nomeia um destino, uma nuvem 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 qual Recipe o tipo de componente PostgreSQL se associa. O gerenciado também associa a Feature de backup que as suas Releases vinculam.
  • release-selfhosted.yaml, release-managed.yaml, release-external.yaml — o dimensionamento do operador em cada Release: armazenamento e versão do mecanismo para a que fica no cluster, armazenamento, HA e uma vinculação core/backup para a gerenciada, e o endereço do servidor existente para a referenciada.
  • release-managed-dns.yaml — a Release gerenciada 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 do banco de dados vem da biblioteca padrão sem modificações.

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 postgres-three-realizations

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

Terminal window
cd postgres-three-realizations

Build

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 grava o arquivo de bloqueio de cada Release no seu primeiro build; os builds seguintes não precisam do flag. Cada um grava em dist/, e um build acrescenta os seus arquivos em vez de limpar o que um anterior deixou. Remova dist/ entre as 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 este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta 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`: ela grava o exemplo em uma nova pasta `postgres-three-realizations`. Em seguida, chame a ferramenta `build` uma vez para cada Release, nesta ordem — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` e `release-external.yaml` — cada vez com `workspace_root` definido como `postgres-three-realizations`, `release` definido como esse arquivo, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos cada build gravou; eles ficam em `postgres-three-realizations/dist/`.

O que cada uma renderiza

Auto-hospedado — a Release executa o servidor

helm/postgres sintetiza o banco de dados no cluster: um StatefulSet, um Service ClusterIP e um Service headless. provides.host é o nome simples desse Service, então a aplicação o alcança pelo DNS interno do cluster.

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

Gerenciado — um provedor de nuvem executa o servidor

terraform/postgres-rds emite um aws_db_instance como HCL do Terraform, e o dimensionamento ha e a vinculação core/backup do operador são mapeados para as configurações nativas da instância: o retention_days: 14 da vinculação se torna o backup_retention_period = 14 da instância. A aplicação continua sendo renderizada para o Kubernetes: os dois lados desta Release se encontram no contrato publicado do banco de dados, não em um destino compartilhado.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

Esse valor não é um hostname, e nada neste build o transforma em um. O endereço de uma instância RDS não existe até que a instância seja criada, então não há nada para um compilador executado antecipadamente consultar. O que a Recipe publica é uma referência do Terraform a uma saída do próprio módulo do banco de dados; o compilador a canaliza pela aresta sem tocá-la, a Recipe da aplicação a recebe literalmente, e ela é renderizada no manifesto do Kubernetes como os caracteres literais mostrados acima. O contêiner recebe esse texto.

DB_PORT é diferente: ele é 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 conexão nativa entre dois componentes é algo que um destino faz dentro da sua própria saída, então aqui não há nenhuma a fazer. As duas pontas desta aresta são renderizadas por destinos diferentes — o banco de dados em HCL do Terraform, a aplicação em um 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 o banco de dados, recebe a mesma referência como um dos argumentos do seu módulo, e ali o Terraform a resolve.

Essa é 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 busca. 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 gerenciada 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 no lugar da referência do Terraform, e a aplicação o recebe:

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 registro DNS nem nenhum alias para o nome, e o build não o resolve: o compilador o canaliza exatamente como canalizou a referência. Fazer db.internal.example.net apontar para a instância depois que ela existir — um registro na própria zona DNS do operador, apontado para o 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 a aceita como um nome simples ou um literal IP, e um valor que traga um esquema, um caminho, um usuário ou uma porta interrompe o build, já que a porta é o infra.port da Release e um consumidor compõe a sua conexão a partir dos dois.

Um consumidor renderizado na mesma configuração do Terraform que o banco 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 em uma fronteira própria que compartilhe o directory: do banco de dados e traga um syncWave: posterior restaura a ordem.

Externo — ninguém nesta Release executa o servidor

helm/postgres-external não provisiona 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 contêiner — 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 controle dele. Esta Recipe alcança um servidor que continua sendo de propriedade externa; nada aqui o coloca sob a gestão da Release, e nada aqui vai alterá-lo.

Omita o endereço e o build para e avisa. Um servidor referenciado tem um endereço ou não tem nada, então a Recipe se recusa em vez de emitir um Service que sirva de alias para 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 ponto central

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

variávelauto-hospedadogerenciadoexterno
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_: ela emite o que quer que a aresta uses tenha resolvido, e é por isso que uma única Recipe é renderizada inalterada contra os três bancos 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. Ele não verifica se alguma delas é roteável, nem se uma porta é um número, nem se um componente chamado db é um banco de dados. Ele associou a aresta pelo rótulo que o Component traz, 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 desenvolvedor não foi tocado por essa escolha. Essa é a separação que o exemplo inteiro existe para tornar concreta:

  • o desenvolvedor diz do que a aplicação precisa de um banco de dados;
  • Ops diz do que um banco de dados é feito — uma Recipe por realização;
  • o operador diz qual delas esta Release recebe, e a dimensiona.

Adicione amanhã uma quarta realização — outra nuvem, outro operador, um serviço do Compose para o trabalho local — e ela é mais uma Recipe publicando as mesmas chaves, mais uma linha de Manifest. O aggregate.yaml neste diretório não muda.