Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Redes entre límites — una intención, dos despliegues

Un stack de dos componentes — una interfaz de base de datos Adminer y una base de datos PostgreSQL — dividido en dos límites, donde Adminer debe llegar a la base de datos a través de la juntura del límite. La misma intención del desarrollador se despliega de dos maneras, y el contraste es la lección:

  • Local (Docker Compose): cada límite es su propia red de compose, y un servicio en uno no puede llegar por nombre a un servicio en el otro. La FeatureRecipe de compose de la Feature core/compose-bridge de la biblioteca estándar genera un gateway aggrega-gw para cruzar esa juntura.
  • Kubernetes (Helm): cada límite es su propio namespace, y un pod en uno llega a un Service en otro mediante el DNS nativo entre namespaces (db-default.backend) — sin puente. La base de datos publica un nombre de servicio simple; la funcionalidad de enrutamiento core/k8s-dns-resolver del consumidor lo cualifica con el namespace de destino.

El compose-bridge es lo que los namespaces de Kubernetes + el DNS entre namespaces te dan de forma nativa. El cruce de la juntura es un asunto de Ops/operador que difiere según el destino; la intención del desarrollador no cambia. La misma anotación de límite aggrega.ai/namespace dirige la ubicación en la red de compose en una variante y la ubicación en el namespace de Kubernetes en la otra.

La intención del desarrollador compartida

aggregate.yaml es idéntico para ambas 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

La única arista uses inyecta el host de la base de datos en ADMINER_DEFAULT_SERVER. A qué se resuelve ese host es un asunto de Ops que se decide por debajo del Aggregate — así que la misma arista produce aggrega-gw:5432 con compose y db-default.backend con helm, sin ningún cambio en la intención del desarrollador.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

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

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

Terminal window
cd cross-boundary-networking

Compilación

Cada variante es una Release, compilada con su propio directorio de catálogo, una Release por ejecución:

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

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `cross-boundary-networking`, llama una vez a la herramienta `scaffold` con `example` establecido en `cross-boundary-networking` y sin `dir`: escribe el ejemplo en una nueva carpeta `cross-boundary-networking`. Después llama a la herramienta `build` con `workspace_root` establecido en `cross-boundary-networking`, `release` establecido en `release-compose.yaml`, `catalog_dirs` establecido en una lista que contiene `catalog-compose`, `auto_pull` establecido en true y `write` establecido en true. Después llama a la herramienta `build` de la misma manera con `release` establecido en `release-helm.yaml` y `catalog_dirs` establecido en una lista que contiene `catalog-helm`. Dime qué archivos escribió cada compilación; están en `cross-boundary-networking/dist/`.

Variante A — local (Docker Compose): el puente

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

Un límite padre bridge contiene dos hijos, frontend (adminer) y backend (db), que comparten un mismo directorio, así que se fusionan en un único dist/bridge/compose/docker-compose.yaml. La anotación aggrega.ai/namespace de cada hijo se convierte en una red de compose. core/compose-bridge, vinculada al padre (ámbito de límite), deriva un gateway aggrega-gw de la arista uses entre redes. Su FeatureRecipe de la biblioteca estándar calcula, una sola vez para el límite, una tabla de las aristas que hay que unir con el puente — ambos extremos en este único archivo de compose, en redes distintas — y todo lo que sigue lo leen sus propias plantillas de esa tabla:

  • su valuesMapping escribe la configuración stream de nginx del gateway, entregada como una config de compose montada (configs: de nivel superior, montada en /etc/nginx/nginx.conf); lleva un resolver y un proxy_pass con variable por arista para que el upstream se resuelva en el momento de la conexión (el $ se escapa como $$ para que la interpolación de Compose lo deje intacto para nginx);
  • el mismo valuesMapping nombra ambos extremos bajo el x-aggrega-networks-of del gateway, que resuelve el proveedor compose, así que el gateway se une a las dos redes unidas por el puente;
  • su injectMapping, ejecutado para adminer, reescribe el ADMINER_DEFAULT_SERVER del consumidor a aggrega-gw:5432. La reescritura sustituye lo que entregó la propia conexión databases de adminer; si otra Feature vinculada a adminer hubiera entregado esa variable, la compilación se detendría nombrando ambas en lugar de sustituirla.

Así, el tráfico fluye adminer → aggrega-gw:5432 → proxy_pass db:5432, cruzando la juntura de red a través del gateway.

Ejecución

Terminal window
cd dist/bridge/compose
docker compose up

Abre http://localhost:8080 (servidor rellenado con aggrega-gw:5432) e inicia sesión:

CampoValor
SistemaPostgreSQL
Servidoraggrega-gw:5432 (rellenado)
Nombre de usuarioappuser
Contraseñaapppass
Base de datosappdb

Las credenciales son solo de demostración (definidas en línea en la recipe del db para que el stack funcione de inmediato); un despliegue real usa el subsistema de credenciales.

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

El mismo Aggregate, desplegado en Kubernetes. Dos límites hermanos, cada uno con una anotación 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

No hay ningún aggrega-gw. La recipe helm db publica un nombre de servicio simple en provides.host — el proveedor helm nombra el Service sintetizado <rendered_name>-<service-key> (db-default), sin namespace. El consumidor vincula la funcionalidad de enrutamiento core/k8s-dns-resolver (la Release la apunta a ADMINER_DEFAULT_SERVER), y la funcionalidad cualifica ese host simple con el namespace del destino en el propio lado del consumidor — y produce el nombre DNS entre namespaces db-default.backend antes de que se renderice Adminer. El host es derivado, no escrito a mano en el productor:

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

Ese valor coincide byte a byte con el metadata.name + metadata.namespace del Service db renderizado, y esa es toda la prueba: el DNS entre namespaces de Kubernetes es un contrato determinista, así que si el host renderizado es igual a la identidad del Service renderizado, se resuelve en tiempo de ejecución — sin gateway, sin necesidad de un clúster activo para verificar el cableado.

La dualidad

compose (Variante A)helm (Variante B)
juntura del límiteredes de compose separadasnamespaces separados
mecanismo de crucegateway de core/compose-bridge (aggrega-gw)DNS nativo entre namespaces
ADMINER_DEFAULT_SERVER se resuelve aaggrega-gw:5432 (reescrito)db-default.backend (cualificado en el lado del llamador)
recurso adicionalel servicio aggrega-gw + su configuraciónninguno
el mismo aggrega.ai/namespace dirigela ubicación en la red de composela ubicación en el namespace de k8s

Una sola intención del desarrollador; el cruce de la juntura es maquinaria de Ops/operador específica del proveedor. El puente de compose existe porque una red de compose plana no tiene DNS con ámbito de namespace; Kubernetes te lo da de forma nativa.

Cuando los dos extremos se renderizan con proveedores distintos

Ambas variantes anteriores mantienen una sola intención del desarrollador y dejan que el cruce se apoye en una cadena puntero determinista: el provides.host de la base de datos fluye a través de la juntura del límite como un puntero estable, y cada destino resuelve ese puntero a su manera — una dirección de gateway de compose, o un nombre DNS entre namespaces. El puntero siempre cruza, porque el compilador canaliza cadenas entre un productor y un consumidor sin interpretarlas.

Un proveedor puede ir más allá y cablear una referencia cruzada nativa entre dos de sus propios artefactos ensamblados a cada lado de la juntura — una referencia en el vocabulario propio de ese proveedor que la plataforma de destino resuelve en el momento del despliegue. El proveedor de CloudFormation lo hace para una arista uses que cruza stacks: el stack productor publica un Export y el stack consumidor lo lee con Fn::ImportValue (consulta providers/cloudformation.md). Una referencia cruzada nativa es una mejora dentro del mismo proveedor — funciona porque ambos extremos hablan el mismo vocabulario de artefactos, así que un lado puede publicar una referencia que el otro sabe resolver.

Cuando una arista uses cruza un límite entre dos proveedores distintos — el productor se ensambla con un proveedor y el consumidor con otro — no es posible ninguna referencia cruzada nativa. Una referencia acuñada en el vocabulario de un proveedor no significa nada para el otro, y el compilador no traduce entre ellos: canaliza cadenas, no infiere significados ni reescribe la referencia de un proveedor en la forma de otro. Así que el puntero determinista del productor cruza la juntura sin cambios; donde cualquiera de los dos proveedores cablea referencias cruzadas nativas propias, como hace CloudFormation, el compilador emite una advertencia que nombra ambos endpoints, los nombres de ambos proveedores y el socket; y la compilación se completa sobre ese puntero. El compilador confía en el autor y no se detiene: un puntero determinista que el autor proporcionó bien puede ser resoluble a través de la juntura — un nombre DNS estable o una cadena de interpolación de infraestructura — y solo el autor conoce la topología de destino.

Esto mantiene el cruce de la juntura donde corresponde. Si un puntero entre proveedores es utilizable es un asunto de despliegue que corresponde al autor; traducir la referencia nativa de un proveedor a la forma consumidora de otro proveedor es un trabajo con opiniones propias y específico del proveedor, que vive fuera del núcleo neutral.

Estructura

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 ejemplo consume la biblioteca estándar. Cada variante se compila con --catalog catalog-<variant>, su propio directorio local, y resuelve lo que ese directorio no declara desde hub.aggrega.ai, el registro predeterminado que nombra .aggrega-config.yaml, así que las entidades locales se resuelven antes que las compartidas. core/datastore/postgres, el componente de interfaz compartido core/devtool/adminer, las Features core/compose-bridge y core/k8s-dns-resolver con sus FeatureRecipes de compose y helm, y los proveedores compose/helm proceden del catálogo estándar. Lo que queda local es el contenido didáctico específico del ejemplo: las recipes de Adminer por destino. La recipe helm db es el helm/postgres de la biblioteca estándar, cuyo provides.host es un nombre de servicio simple y autocontenido. El consumidor lo cualifica con el namespace de destino en el lado del llamador mediante la funcionalidad de enrutamiento core/k8s-dns-resolver de la biblioteca estándar, así que la recipe no fija en el código ningún namespace de límite.

En una variante compilada se encuentran dos categorías de archivos: entradas escritas (todo lo anterior) y salida generada por el compilador bajo dist/ (el docker-compose.yaml fusionado, o los manifiestos de helm por namespace) — no escribes nada de esta última. dist/ lo regenera aggrega build y git lo ignora.