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-bridgeda biblioteca padrão gera um gatewayaggrega-gwpara 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 roteamentocore/k8s-dns-resolverdo 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/postgresA ú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:
aggrega scaffold --example cross-boundary-networkingEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd cross-boundary-networkingBuild
Cada variante é uma Release, compilada com o seu próprio diretório de catálogo, uma Release por execução:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmCom 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
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeUma 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
valuesMappingescreve a configuraçãostreamdo nginx do gateway, entregue como uma config do compose montada (configs:de nível superior, montada em/etc/nginx/nginx.conf); ela traz umresolvere umproxy_passcom 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
valuesMappingnomeia as duas pontas sob ox-aggrega-networks-ofdo 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 oADMINER_DEFAULT_SERVERdo consumidor paraaggrega-gw:5432. A reescrita substitui o que a própria conexãodatabasesdo 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
cd dist/bridge/composedocker compose upAbra http://localhost:8080 (servidor preenchido com aggrega-gw:5432) e faça login:
| Campo | Valor |
|---|---|
| Sistema | PostgreSQL |
| Servidor | aggrega-gw:5432 (preenchido) |
| Nome de usuário | appuser |
| Senha | apppass |
| Banco de dados | appdb |
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
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmO 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: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendNã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:
- 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 fronteira | redes do compose separadas | namespaces separados |
| mecanismo de travessia | gateway de core/compose-bridge (aggrega-gw) | DNS nativo entre namespaces |
ADMINER_DEFAULT_SERVER se resolve para | aggrega-gw:5432 (reescrito) | db-default.backend (qualificado no lado do chamador) |
| recurso adicional | o serviço aggrega-gw + a sua configuração | nenhum |
o mesmo aggrega.ai/namespace determina | o posicionamento na rede do compose | o 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.