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

Rede entre fronteiras — uma intenção, duas implantações

Um stack de dois componentes — uma interface de banco de dados Adminer e um banco de dados PostgreSQL — dividido em duas fronteiras, em que o Adminer precisa alcançar o banco de dados através da junção da fronteira. A mesma intenção do desenvolvedor é implantada de duas maneiras, e o contraste é a lição:

  • Local (Docker Compose): cada fronteira é a sua própria rede do compose, e um serviço em uma não consegue alcançar um serviço na outra pelo nome. A FeatureRecipe do compose da Feature core/compose-bridge da biblioteca padrão gera um gateway aggrega-gw para atravessar essa junção.
  • Kubernetes (Helm): cada fronteira é o seu próprio namespace, e um pod em um alcança um Service em outro pelo DNS nativo entre namespaces (db-default.backend) — sem ponte. O banco de dados publica um nome de serviço simples; a funcionalidade de roteamento core/k8s-dns-resolver do consumidor o qualifica com o namespace de destino.

O compose-bridge é o que os namespaces do Kubernetes + o DNS entre namespaces oferecem nativamente a você. A travessia da junção é uma preocupação de Ops/operador que difere conforme o destino; a intenção do desenvolvedor não muda. A mesmíssima anotação de fronteira aggrega.ai/namespace determina o posicionamento na rede do compose em uma variante e o posicionamento no namespace do Kubernetes na outra.

A intenção do desenvolvedor compartilhada

aggregate.yaml é idêntico para as duas variantes:

components:
adminer:
type: core/devtool/adminer
uses:
databases:
primary:
target: db
inject:
env:
- in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant
from: host # ← the target db's provides.host
db:
type: core/datastore/postgres

A única aresta uses injeta o host do banco de dados em ADMINER_DEFAULT_SERVER. Em que se resolve esse host é uma preocupação de Ops decidida abaixo do Aggregate — então a mesma aresta produz aggrega-gw:5432 com compose e db-default.backend com helm, sem nenhuma mudança na intenção do desenvolvedor.

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 cross-boundary-networking

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

Terminal window
cd cross-boundary-networking

Build

Cada variante é uma Release, compilada com o seu próprio diretório de catálogo, uma Release por execução:

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

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 por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `cross-boundary-networking`, chame uma vez a ferramenta `scaffold` com `example` definido como `cross-boundary-networking` e sem `dir`: ela grava o exemplo em uma nova pasta `cross-boundary-networking`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `cross-boundary-networking`, `release` definido como `release-compose.yaml`, `catalog_dirs` definido como uma lista contendo `catalog-compose`, `auto_pull` definido como true e `write` definido como true. Em seguida, chame a ferramenta `build` da mesma forma com `release` definido como `release-helm.yaml` e `catalog_dirs` definido como uma lista contendo `catalog-helm`. Diga-me quais arquivos cada build gravou; eles ficam em `cross-boundary-networking/dist/`.

Variante A — local (Docker Compose): a ponte

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose

Uma fronteira pai bridge contém duas filhas, frontend (adminer) e backend (db), que compartilham um único diretório e por isso se fundem em um único dist/bridge/compose/docker-compose.yaml. A anotação aggrega.ai/namespace de cada filha se torna uma rede do compose. core/compose-bridge, vinculada à fronteira pai (escopo de fronteira), deriva um gateway aggrega-gw da aresta uses entre redes. A sua FeatureRecipe da biblioteca padrão calcula, uma única vez para a fronteira, uma tabela das arestas a ligar pela ponte — as duas pontas neste único arquivo do compose, em redes diferentes — e tudo o que segue é lido dessa tabela pelos seus próprios templates:

  • o seu valuesMapping escreve a configuração stream do nginx do gateway, entregue como uma config do compose montada (configs: de nível superior, montada em /etc/nginx/nginx.conf); ela traz um resolver e um proxy_pass com variável por aresta para que o upstream se resolva no momento da conexão (o $ é escapado como $$ para que a interpolação do Compose o deixe intacto para o nginx);
  • o mesmo valuesMapping nomeia as duas pontas sob o x-aggrega-networks-of do gateway, que o provedor compose resolve, então o gateway entra nas duas redes ligadas pela ponte;
  • o seu injectMapping, executado para o adminer, reescreve o ADMINER_DEFAULT_SERVER do consumidor para aggrega-gw:5432. A reescrita substitui o que a própria conexão databases do adminer entregou; se outra Feature vinculada ao adminer tivesse entregado essa variável, o build seria interrompido nomeando as duas em vez de substituí-la.

Assim, o tráfego flui adminer → aggrega-gw:5432 → proxy_pass db:5432, atravessando a junção de rede pelo gateway.

Execução

Terminal window
cd dist/bridge/compose
docker compose up

Abra http://localhost:8080 (servidor preenchido com aggrega-gw:5432) e faça login:

CampoValor
SistemaPostgreSQL
Servidoraggrega-gw:5432 (preenchido)
Nome de usuárioappuser
Senhaapppass
Banco de dadosappdb

As credenciais são apenas para demonstração (definidas inline na recipe do db para que o stack funcione de imediato); uma implantação real usa o subsistema de credenciais.

Variante B — Kubernetes (Helm): namespaces + DNS entre namespaces

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

O mesmo Aggregate, implantado no Kubernetes. Duas fronteiras irmãs, cada uma com uma anotação aggrega.ai/namespace distinta que se propaga para cada recurso como metadata.namespace:

dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/backend/helm/db-headless-service.yaml # metadata.namespace: backend

Não há nenhum aggrega-gw. A recipe helm db publica um nome de serviço simples em provides.host — o provedor helm nomeia o Service sintetizado <rendered_name>-<service-key> (db-default), sem namespace. O consumidor vincula a funcionalidade de roteamento core/k8s-dns-resolver (a Release a aponta para ADMINER_DEFAULT_SERVER), e a funcionalidade qualifica esse host simples com o namespace do destino no próprio lado do consumidor — produzindo o nome DNS entre namespaces db-default.backend antes de o Adminer ser renderizado. O host é derivado, não escrito à mão no produtor:

dist/frontend/helm/adminer-deployment.yaml
- name: ADMINER_DEFAULT_SERVER
value: db-default.backend # == the rendered db Service <name>.<namespace>

Esse valor corresponde byte a byte ao metadata.name + metadata.namespace do Service db renderizado, e essa é toda a prova: o DNS entre namespaces do Kubernetes é um contrato determinístico, então se o host renderizado for igual à identidade do Service renderizado, ele se resolve em tempo de execução — sem gateway, sem precisar de um cluster ativo para verificar a ligação.

A dualidade

compose (Variante A)helm (Variante B)
junção da fronteiraredes do compose separadasnamespaces separados
mecanismo de travessiagateway de core/compose-bridge (aggrega-gw)DNS nativo entre namespaces
ADMINER_DEFAULT_SERVER se resolve paraaggrega-gw:5432 (reescrito)db-default.backend (qualificado no lado do chamador)
recurso adicionalo serviço aggrega-gw + a sua configuraçãonenhum
o mesmo aggrega.ai/namespace determinao posicionamento na rede do composeo posicionamento no namespace do k8s

Uma única intenção do desenvolvedor; a travessia da junção é um mecanismo de Ops/operador específico do provedor. A ponte do compose existe porque uma rede plana do compose não tem DNS com escopo de namespace; o Kubernetes oferece isso nativamente a você.

Quando as duas pontas são renderizadas por provedores diferentes

As duas variantes acima mantêm uma única intenção do desenvolvedor e deixam a travessia se apoiar em uma string de ponteiro determinística: o provides.host do banco de dados flui pela junção da fronteira como um ponteiro estável, e cada destino resolve esse ponteiro à sua maneira — um endereço de gateway do compose, ou um nome DNS entre namespaces. O ponteiro sempre atravessa, porque o compilador encaminha strings entre um produtor e um consumidor sem interpretá-las.

Um provedor pode ir além e ligar uma referência cruzada nativa entre dois dos seus próprios artefatos montados em cada lado da junção — uma referência no vocabulário próprio desse provedor que a plataforma de destino resolve no momento da implantação. O provedor do CloudFormation faz isso para uma aresta uses que atravessa stacks: o stack produtor publica um Export e o stack consumidor o lê com Fn::ImportValue (veja providers/cloudformation.md). Uma referência cruzada nativa é uma melhoria dentro do mesmo provedor — funciona porque as duas pontas falam o mesmo vocabulário de artefatos, então um lado pode publicar uma referência que o outro lado sabe resolver.

Quando uma aresta uses atravessa uma fronteira entre dois provedores diferentes — o produtor é montado sob um provedor e o consumidor sob outro —, nenhuma referência cruzada nativa é possível. Uma referência cunhada no vocabulário de um provedor não significa nada para o outro, e o compilador não traduz entre eles: ele encaminha strings, não infere significado nem reescreve a referência de um provedor na forma de outro. Assim, o ponteiro determinístico do produtor atravessa a junção sem alterações; onde qualquer um dos dois provedores liga referências cruzadas nativas próprias, como faz o CloudFormation, o compilador emite um aviso que nomeia os dois endpoints, os nomes dos dois provedores e o socket; e o build é concluído sobre esse ponteiro. O compilador confia no autor e não é interrompido: um ponteiro determinístico fornecido pelo autor pode muito bem ser resolvível através da junção — um nome DNS estável ou uma string de interpolação de infraestrutura — e só o autor conhece a topologia de destino.

Isso mantém a travessia da junção onde ela pertence. Se um ponteiro entre provedores é utilizável é uma questão de implantação que cabe ao autor; traduzir a referência nativa de um provedor para a forma consumidora de outro provedor é um trabalho com opiniões próprias e específico do provedor, que fica fora do núcleo neutro.

Estrutura

cross-boundary-networking/
├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry
├── aggregate.yaml # SHARED developer intent (both variants)
├── release-compose.yaml # Variant A: parent bridge boundary + two networks
├── manifest-compose.yaml
├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)
├── release-helm.yaml # Variant B: two namespace boundaries, no bridge
├── manifest-helm.yaml
└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)

Este exemplo consome a biblioteca padrão. Cada variante é compilada com --catalog catalog-<variant>, o seu próprio diretório local, e resolve o que esse diretório não declara a partir de hub.aggrega.ai, o registro padrão que .aggrega-config.yaml nomeia, então as entidades locais são resolvidas antes das compartilhadas. core/datastore/postgres, o componente de interface compartilhado core/devtool/adminer, as Features core/compose-bridge e core/k8s-dns-resolver com as suas FeatureRecipes de compose e helm, e os provedores compose/helm vêm do catálogo padrão. O que fica local é o conteúdo didático específico do exemplo: as recipes do Adminer por destino. A recipe helm db é o helm/postgres da biblioteca padrão, cujo provides.host é um nome de serviço simples e autossuficiente. O consumidor o qualifica com o namespace de destino no lado do chamador por meio da funcionalidade de roteamento core/k8s-dns-resolver da biblioteca padrão, então a recipe não fixa no código nenhum namespace de fronteira.

Duas categorias de arquivo se encontram em uma variante compilada: entradas escritas (tudo o que está acima) e saída gerada pelo compilador em dist/ (o docker-compose.yaml mesclado, ou os manifestos do helm por namespace) — você não escreve nada desta última. dist/ é regenerado por aggrega build e é ignorado pelo git.