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

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-bridge da biblioteca standard gera um gateway aggrega-gw para 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 encaminhamento core/k8s-dns-resolver do 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/postgres

A ú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:

Terminal window
aggrega scaffold --example cross-boundary-networking

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

Terminal window
cd cross-boundary-networking

Compilação

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

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

Uma 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 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); traz um resolver e um proxy_pass com 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 valuesMapping nomeia as duas pontas sob o x-aggrega-networks-of do 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 o ADMINER_DEFAULT_SERVER do consumidor para aggrega-gw:5432. A reescrita substitui o que a própria ligação databases do 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

Terminal window
cd dist/bridge/compose
docker compose up

Abrir http://localhost:8080 (servidor preenchido com aggrega-gw:5432) e iniciar sessão:

CampoValor
SistemaPostgreSQL
Servidoraggrega-gw:5432 (preenchido)
Nome de utilizadorappuser
Palavra-passeapppass
Base de dadosappdb

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

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

O 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: 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 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:

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, 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 fronteiraredes do compose separadasnamespaces separados
mecanismo de travessiagateway de core/compose-bridge (aggrega-gw)DNS nativo entre namespaces
ADMINER_DEFAULT_SERVER resolve-se 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 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.