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

Un contrato, tres realizaciones

Una base de datos PostgreSQL y la aplicación que la lee, desplegadas de tres formas distintas a partir de un único Aggregate sin cambios: PostgreSQL ejecutándose en el clúster, PostgreSQL como instancia gestionada en la nube y un servidor PostgreSQL que ya existía antes de que se desplegara esta Release.

La lección es lo que no cambia. La aplicación nombra, una sola vez, las claves que quiere de la base de datos y cómo llamarlas. Nunca sabe cuál de las tres respondió. El compilador tampoco lo sabe: lee las claves que publicó la Recipe seleccionada y encamina las cadenas.

Lo único que varía

.-- helm/postgres ---------- a StatefulSet in the cluster
/
core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform
one Component \
one contract '- helm/postgres-external -- a server that already exists

Tres Recipes implementan el mismo Component. Cada una publica las mismas claves provides — host, port, user, database, protocol y las claves que indican dónde encuentra un scraper las métricas de la base de datos, vacías en las tres. Cuál se ejecuta es una sola línea del Manifest.

Archivos

  • aggregate.yaml — la intención del desarrollador, y el mismo documento para las tres Releases: un componente db de tipo core/datastore/postgres, una app que lo usa mediante uses, y las cinco claves que pide la aplicación. Nada aquí nombra un destino, una nube o una Recipe.
  • manifest-selfhosted.yaml, manifest-managed.yaml, manifest-external.yaml — las asignaciones de Ops. Cada una elige su realización en una línea: con qué Recipe se enlaza el tipo de componente PostgreSQL. La gestionada enlaza además la Feature de copia de seguridad que vinculan sus Releases.
  • release-selfhosted.yaml, release-managed.yaml, release-external.yaml — el dimensionamiento del operador en cada Release: almacenamiento y versión del motor para la que está en el clúster, almacenamiento, HA y una vinculación core/backup para la gestionada, y la dirección del servidor existente para la referenciada.
  • release-managed-dns.yaml — la Release gestionada una vez más, con el nombre DNS que el operador da a la instancia, de modo que la aplicación recibe un nombre que puede resolver.
  • catalog/ — el Component propio de la aplicación y la única Recipe que lo renderiza. Todo lo que hay del lado de la base de datos procede de la biblioteca estándar sin modificar.

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 postgres-three-realizations

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

Terminal window
cd postgres-three-realizations

Compilación

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull escribe el archivo de bloqueo de cada Release en su primera compilación; las compilaciones posteriores no necesitan el flag. Cada una escribe en dist/, y una compilación añade sus archivos en lugar de borrar lo que dejó una anterior. Elimina dist/ entre ejecuciones para leer por sí sola la salida de una realización:

Terminal window
rm -rf dist && aggrega build --release release-managed.yaml

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 Workspace aún no contiene una carpeta `postgres-three-realizations`, llama una vez a la herramienta `scaffold` con `example` establecido en `postgres-three-realizations` y sin `dir`: escribe el ejemplo en una nueva carpeta `postgres-three-realizations`. Luego llama a la herramienta `build` una vez por cada Release, en este orden — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` y `release-external.yaml` — cada vez con `workspace_root` establecido en `postgres-three-realizations`, `release` establecido en ese archivo, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió cada compilación; están en `postgres-three-realizations/dist/`.

Qué renderiza cada una

Autoalojado — la Release ejecuta el servidor

helm/postgres sintetiza la base de datos en el clúster: un StatefulSet, un Service ClusterIP y un Service headless. provides.host es el nombre simple de ese Service, así que la aplicación lo alcanza por el DNS interno del clúster.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

Gestionado — un proveedor de nube ejecuta el servidor

terraform/postgres-rds emite un aws_db_instance como HCL de Terraform, y el dimensionamiento ha y la vinculación core/backup del operador se asignan a los ajustes nativos de la instancia: el retention_days: 14 de la vinculación se convierte en el backup_retention_period = 14 de la instancia. La aplicación sigue renderizándose en Kubernetes: los dos lados de esta Release se encuentran en el contrato publicado de la base de datos, no en un destino compartido.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

Ese valor no es un nombre de host, y nada en esta compilación lo convierte en uno. La dirección de una instancia RDS no existe hasta que se crea la instancia, así que no hay nada que consultar para un compilador que se ejecuta de antemano. Lo que publica la Recipe es una referencia de Terraform a una salida del propio módulo de la base de datos; el compilador la canaliza por la arista sin tocarla, la Recipe de la aplicación la recibe tal cual, y se renderiza en el manifiesto de Kubernetes como los caracteres literales mostrados arriba. Al contenedor se le entrega ese texto.

DB_PORT es distinto: se renderiza como "5432", porque la Recipe establece el puerto de la instancia a partir de la Release y publica ese mismo valor, que se conoce antes de que exista nada.

El cableado nativo entre dos componentes es algo que un destino hace dentro de su propia salida, así que aquí no hay ninguno que hacer. Los dos extremos de esta arista se renderizan mediante destinos distintos — la base de datos en HCL de Terraform, la aplicación en un manifiesto de Kubernetes — y una referencia de Terraform solo tiene significado dentro de una configuración de Terraform. Al cruzar esa juntura, el valor publicado se entrega como texto, igual que cualquier otra cadena. Un consumidor renderizado en Terraform como Recipe source:, en la misma configuración raíz que la base de datos, recibe la misma referencia como uno de los argumentos de su módulo, y allí Terraform la resuelve.

Esta es la regla general y no un caso especial para RDS: todo lo que depende del estado de un sistema en ejecución se expresa como un puntero determinista que resuelve el runtime, nunca como un valor que el compilador obtiene. La parte del compilador es entregar el puntero sin cambios. Lograr que se resuelva donde llega le corresponde al autor de la Recipe: publicar una dirección que el lado consumidor pueda usar, o dar a ambos componentes Recipes que rendericen en el mismo destino.

Dar a la instancia un nombre que la aplicación pueda resolver

terraform/postgres-rds acepta la primera de ellas como una opción que establece el operador. release-managed-dns.yaml es la Release gestionada con un añadido, el nombre DNS que el operador da a la instancia:

db:
infra:
overrides:
host: db.internal.example.net

La Recipe publica ese nombre como host en lugar de la referencia de Terraform, y la aplicación lo recibe:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
variablerelease-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

Es la única línea de la salida que cambia. La Recipe no emite ningún registro DNS ni ningún alias para el nombre, y la compilación no lo resuelve: el compilador lo canaliza exactamente como canalizó la referencia. Hacer que db.internal.example.net apunte a la instancia una vez que existe — un registro en la propia zona DNS del operador, dirigido a la dirección de la instancia — le corresponde al operador, fuera de la Release. La clave es la que la realización referenciada más abajo lee para la misma dirección; esta Recipe la acepta como un nombre simple o un literal IP, y un valor que lleve un esquema, una ruta, un usuario o un puerto detiene la compilación, ya que el puerto es el infra.port de la Release y un consumidor compone su conexión a partir de ambos.

Un consumidor renderizado en la misma configuración de Terraform que la base de datos también recibe el nombre, y con él pierde el orden que le daba la referencia: Terraform actúa sobre un módulo después de un módulo al que referencia, y un nombre no referencia nada. Colocar ese consumidor en un límite propio que comparta el directory: de la base de datos y lleve un syncWave: posterior restablece el orden.

Externo — nadie en esta Release ejecuta el servidor

helm/postgres-external no aprovisiona nada en absoluto. Toda su salida es un Service que asigna un nombre interno del clúster a la dirección que proporciona la Release:

dist/stack/helm/db-service.yaml
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]
spec:
type: ExternalName
externalName: postgres.data.example.net
ports:
- port: 5432

Ningún StatefulSet, ningún volumen, ningún contenedor — el ciclo de vida del servidor queda por completo fuera de esta Release. La dirección viene de la Release:

db:
infra:
overrides:
host: postgres.data.example.net
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

Referenciar un servidor no es lo mismo que hacerse cargo de él. Esta Recipe alcanza un servidor que sigue siendo de propiedad externa; nada aquí lo pone bajo la gestión de la Release, y nada aquí lo cambiará.

Omite la dirección y la compilación se detiene y lo indica. Un servidor referenciado tiene una dirección o no tiene nada, así que la Recipe se niega en lugar de emitir un Service que sea alias de un nombre vacío:

[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]
assertion failed: the Manifest selects the referenced realization of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

La comparación que es el objetivo

El entorno renderizado de la aplicación, los tres lado a lado:

variableautoalojadogestionadoexterno
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

Mismas variables, mismo orden, siempre. Solo cambia la cadena detrás de una de ellas. La Recipe de la aplicación no nombra ninguna de las variables DB_: emite lo que haya resuelto la arista uses, y por eso una sola Recipe se renderiza sin cambios frente a las tres bases de datos.

Y el compilador no sabe qué son esas cadenas. db-default es un nombre de Service de Kubernetes, ${module.db.address} es una referencia de Terraform, postgres.data.example.net es un nombre DNS — para el compilador son tres cadenas que una Recipe publicó bajo la clave host y que una arista pidió que se entregaran como DB_HOST. No comprueba que ninguna de ellas sea enrutable, ni que un puerto sea un número, ni que un componente llamado db sea una base de datos. Emparejó la arista por la etiqueta que lleva el Component, leyó la clave que declara el contrato y movió el texto.

Dónde está la costura

Cada una de las tres Releases la eligió una asignación de Ops, y el documento del desarrollador no se vio afectado por esa elección. Esa es la separación que todo el ejemplo existe para hacer concreta:

  • el desarrollador dice qué necesita la aplicación de una base de datos;
  • Ops dice de qué está hecha una base de datos — una Recipe por realización;
  • el operador dice cuál recibe esta Release, y la dimensiona.

Añade mañana una cuarta realización — otra nube, otro operador, un servicio de Compose para el trabajo local — y se trata de una Recipe más que publica las mismas claves, más una línea de Manifest. El aggregate.yaml de este directorio no cambia.