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-bridgede la biblioteca estándar genera un gatewayaggrega-gwpara 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 enrutamientocore/k8s-dns-resolverdel 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/postgresLa ú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:
aggrega scaffold --example cross-boundary-networkingDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd cross-boundary-networkingCompilación
Cada variante es una Release, compilada con su propio directorio de catálogo, una Release por ejecución:
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-helmCon 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
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeUn 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
valuesMappingescribe la configuraciónstreamde nginx del gateway, entregada como una config de compose montada (configs:de nivel superior, montada en/etc/nginx/nginx.conf); lleva unresolvery unproxy_passcon 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
valuesMappingnombra ambos extremos bajo elx-aggrega-networks-ofdel 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 elADMINER_DEFAULT_SERVERdel consumidor aaggrega-gw:5432. La reescritura sustituye lo que entregó la propia conexióndatabasesde 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
cd dist/bridge/composedocker compose upAbre http://localhost:8080 (servidor rellenado con aggrega-gw:5432) e inicia sesión:
| Campo | Valor |
|---|---|
| Sistema | PostgreSQL |
| Servidor | aggrega-gw:5432 (rellenado) |
| Nombre de usuario | appuser |
| Contraseña | apppass |
| Base de datos | appdb |
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
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmEl 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: 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: backendNo 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:
- 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ímite | redes de compose separadas | namespaces separados |
| mecanismo de cruce | gateway de core/compose-bridge (aggrega-gw) | DNS nativo entre namespaces |
ADMINER_DEFAULT_SERVER se resuelve a | aggrega-gw:5432 (reescrito) | db-default.backend (cualificado en el lado del llamador) |
| recurso adicional | el servicio aggrega-gw + su configuración | ninguno |
el mismo aggrega.ai/namespace dirige | la ubicación en la red de compose | la 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.