Rede entre fronteiras — uma intenção, duas implementações
Uma stack de dois componentes — uma interface de base de dados Adminer e uma base de dados PostgreSQL — dividida em duas fronteiras, em que o Adminer tem de alcançar a base de dados através da junção da fronteira. A mesma intenção do programador é implementada 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 numa não consegue alcançar um serviço na outra pelo nome. A FeatureRecipe do compose da Feature
core/compose-bridgeda biblioteca standard gera um gatewayaggrega-gwpara atravessar essa junção. - Kubernetes (Helm): cada fronteira é o seu próprio namespace, e um pod num alcança um Service noutro através do DNS nativo entre namespaces (
db-default.backend) — sem ponte. A base de dados publica um nome de serviço simples; a funcionalidade de encaminhamentocore/k8s-dns-resolverdo consumidor qualifica-o com o namespace de destino.
O compose-bridge é o que os namespaces do Kubernetes + o DNS entre namespaces oferecem nativamente. A travessia da junção é uma questão de Ops/operador que difere conforme o destino; a intenção do programador não muda. A mesmíssima anotação de fronteira aggrega.ai/namespace determina o posicionamento na rede do compose numa variante e o posicionamento no namespace do Kubernetes na outra.
A intenção do programador partilhada
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 da base de dados em ADMINER_DEFAULT_SERVER. Em que se resolve esse anfitrião é uma questão de Ops decidida abaixo do Aggregate — pelo que a mesma aresta produz aggrega-gw:5432 com compose e db-default.backend com helm, sem nenhuma alteração à intenção do programador.
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 cross-boundary-networkingDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd cross-boundary-networkingCompilação
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-lhe este prompt.
Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver uma pasta `cross-boundary-networking`, chame uma vez a ferramenta `scaffold` com `example` definido como `cross-boundary-networking` e sem `dir`: esta escreve o exemplo numa 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 que contém `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 que contém `catalog-helm`. Indique-me que ficheiros cada build escreveu; encontram-se 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 mãe bridge contém duas filhas, frontend (adminer) e backend (db), que partilham um único diretório e por isso se fundem num único dist/bridge/compose/docker-compose.yaml. A anotação aggrega.ai/namespace de cada filha torna-se uma rede do compose. core/compose-bridge, anexada à fronteira mãe (âmbito de fronteira), deriva um gateway aggrega-gw da aresta uses entre redes. A sua FeatureRecipe da biblioteca standard calcula, uma única vez para a fronteira, uma tabela das arestas a ligar pela ponte — as duas pontas neste único ficheiro do compose, em redes diferentes — e tudo o que se 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); traz umresolvere umproxy_passcom variável por aresta para que o upstream se resolva no momento da ligaçã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 fornecedor compose resolve, pelo que o gateway se junta às 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 ligaçãodatabasesdo adminer entregou; se outra Feature anexada ao adminer tivesse entregado essa variável, a compilação seria interrompida nomeando as duas em vez de a substituir.
Assim, o tráfego flui adminer → aggrega-gw:5432 → proxy_pass db:5432, atravessando a junção de rede através do gateway.
Execução
cd dist/bridge/composedocker compose upAbrir http://localhost:8080 (servidor preenchido com aggrega-gw:5432) e iniciar sessão:
| Campo | Valor |
|---|---|
| Sistema | PostgreSQL |
| Servidor | aggrega-gw:5432 (preenchido) |
| Nome de utilizador | appuser |
| Palavra-passe | apppass |
| Base de dados | appdb |
As credenciais são apenas para demonstração (definidas inline na recipe do db para que a stack funcione de imediato); uma implementaçã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, implementado no Kubernetes. Duas fronteiras irmãs, cada uma com uma anotação aggrega.ai/namespace distinta que se propaga a 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 fornecedor helm nomeia o Service sintetizado <rendered_name>-<service-key> (db-default), sem namespace. O consumidor anexa a funcionalidade de encaminhamento core/k8s-dns-resolver (a Release aponta-a para ADMINER_DEFAULT_SERVER), e a funcionalidade qualifica esse anfitrião 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 anfitrião é 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, pelo que, se o anfitrião renderizado for igual à identidade do Service renderizado, resolve-se em tempo de execução — sem gateway, sem necessidade 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 resolve-se 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 programador; a travessia da junção é um mecanismo de Ops/operador específico do fornecedor. A ponte do compose existe porque uma rede plana do compose não tem DNS com âmbito de namespace; o Kubernetes oferece-o nativamente.
Quando as duas pontas são renderizadas por fornecedores diferentes
As duas variantes acima mantêm uma única intenção do programador e deixam a travessia apoiar-se numa string de ponteiro determinística: o provides.host da base 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 atravessa sempre, porque o compilador encaminha strings entre um produtor e um consumidor sem as interpretar.
Um fornecedor pode ir mais longe e ligar uma referência cruzada nativa entre dois dos seus próprios artefactos montados de cada lado da junção — uma referência no vocabulário próprio desse fornecedor que a plataforma de destino resolve no momento da implementação. O fornecedor do CloudFormation fá-lo para uma aresta uses que atravessa stacks: a stack produtora publica um Export e a stack consumidora lê-o com Fn::ImportValue (veja-se providers/cloudformation.md). Uma referência cruzada nativa é uma melhoria dentro do mesmo fornecedor — funciona porque as duas pontas falam o mesmo vocabulário de artefactos, pelo que um lado pode publicar uma referência que o outro lado sabe resolver.
Quando uma aresta uses atravessa uma fronteira entre dois fornecedores diferentes — o produtor é montado sob um fornecedor e o consumidor sob outro —, nenhuma referência cruzada nativa é possível. Uma referência cunhada no vocabulário de um fornecedor não significa nada para o outro, e o compilador não traduz entre eles: encaminha strings, não infere significado nem reescreve a referência de um fornecedor na forma de outro. Assim, o ponteiro determinístico do produtor atravessa a junção sem alterações; onde qualquer um dos dois fornecedores 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 fornecedores e o socket; e a compilação conclui-se sobre esse ponteiro. O compilador confia no autor e não se interrompe: um ponteiro determinístico fornecido pelo autor pode muito bem ser resolú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.
Isto mantém a travessia da junção onde pertence. Saber se um ponteiro entre fornecedores é utilizável é uma questão de implementação que cabe ao autor; traduzir a referência nativa de um fornecedor para a forma consumidora de outro fornecedor é um trabalho com opiniões próprias e específico do fornecedor, 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 standard. 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 registo predefinido que .aggrega-config.yaml nomeia, pelo que as entidades locais se resolvem antes das partilhadas. core/datastore/postgres, o componente de interface partilhado core/devtool/adminer, as Features core/compose-bridge e core/k8s-dns-resolver com as suas FeatureRecipes de compose e helm, e os fornecedores compose/helm vêm do catálogo standard. 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 standard, cujo provides.host é um nome de serviço simples e autossuficiente. O consumidor qualifica-o com o namespace de destino do lado do chamador através da funcionalidade de encaminhamento core/k8s-dns-resolver da biblioteca standard, pelo que a recipe não fixa no código nenhum namespace de fronteira.
Duas categorias de ficheiro encontram-se numa variante compilada: entradas escritas (tudo o que está acima) e saída gerada pelo compilador em dist/ (o docker-compose.yaml fundido, ou os manifestos do helm por namespace) — desta última não se escreve nada. dist/ é regenerado por aggrega build e é ignorado pelo git.