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

Stack de FerretDB — una base de datos documental compuesta como módulo

Este ejemplo compila un stack pequeño y real — una base de datos documental que expone el protocolo de red de MongoDB — a manifiestos de Kubernetes sintetizados a partir de un único Aggregate escrito por el desarrollador.

La base de datos documental no es un componente único. Es un módulo: un subagregado reutilizable que compone dos componentes de una sola carga de trabajo —

  • un proxy que habla el protocolo de red de MongoDB y no guarda estado local, y
  • un backend, PostgreSQL 17 con la extensión DocumentDB, que persiste los datos en un volumen.

El módulo conecta su propia arista interna del proxy al backend y exporta el proxy como su endpoint público mongo. El Aggregate de nivel superior importa el módulo por nombre y renderiza el stack compuesto; el operador dimensiona los componentes internos del módulo en la Release.

Archivos

ArchivoRol
aggregate.yamlIntención del desarrollador: importa el módulo de base de datos documental (core/ferretdb).
manifest-helm-synth.yamlAsigna los tipos proxy y backend a sus Recipes helm synth.
release-helm-synth.yamlDocumento del operador para el destino Kubernetes. Dimensiona los componentes internos del módulo por sus ID con ámbito de módulo; todo lo que queda en los valores predeterminados del esquema se renderiza de forma autónoma.

Lo que demuestra

  • Composición como módulo. Una capacidad de varias cargas de trabajo — una base de datos documental que en realidad es un proxy más un backend de almacenamiento — se empaqueta como un subagregado que compone dos componentes de una sola carga de trabajo, no como un único componente monolítico. El módulo se importa por nombre y se reutiliza dondequiera que se necesite una base de datos documental.
  • Una arista interna dentro del módulo. El proxy declara un uso del backend; el host, el puerto, el usuario y la base de datos de los provides de la Recipe del backend se canalizan al proxy y se componen en su conexión a PostgreSQL. El compilador enruta las cadenas sin interpretarlas.
  • Un endpoint público. El módulo exporta su proxy como mongo, el nombre público estable al que se conecta un consumidor de la base de datos documental — desacoplado de los nombres de los componentes internos del módulo.
  • Dimensionamiento de los componentes internos por parte del operador. La Release se dirige a los componentes internos del módulo por sus ID con ámbito de módulo (database.backend, database.proxy) para establecer el cómputo, sin que el Aggregate del desarrollador repita el dimensionamiento físico.
  • Una credencial compartida. El proxy delega la autenticación en su backend PostgreSQL, así que los dos comparten una única contraseña. Este ejemplo usa un valor predeterminado de desarrollo compartido y escrito en línea, así que el stack se ejecuta de forma autónoma sin ningún secreto externo.
  • Una cadena de conexión sin contraseña. La URL de conexión a PostgreSQL del proxy se renderiza sin la contraseña incrustada; la contraseña se proporciona por separado en la variable de entorno estándar de libpq PGPASSWORD, que el controlador incorpora a la conexión. Así la credencial queda fuera de la cadena de conexión en el manifiesto renderizado.
  • Imágenes reproducibles. Tanto el proxy como el backend fijan tags de imagen explícitos, así que los manifiestos renderizados hacen referencia a imágenes estables.

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

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

Terminal window
cd ferretdb-stack

Compilación

Este workspace no lleva ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no se necesita ningún flag de catálogo; --auto-pull escribe durante la compilación el lockfile que le falta a un clon recién creado:

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

Los artefactos renderizados quedan en dist/. El destino Kubernetes renderiza manifiestos simples sin conexión — no se requiere ningún pull de chart.

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 `ferretdb-stack`, llama una vez a la herramienta `scaffold` con `example` establecido en `ferretdb-stack` y sin `dir`: escribe el ejemplo en una nueva carpeta `ferretdb-stack`. Después llama a la herramienta `build` con `workspace_root` establecido en `ferretdb-stack`, `release` establecido en `release-helm-synth.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `ferretdb-stack/dist/`.

Cómo es el stack compuesto

El proxy se renderiza como un Deployment sin estado más un Service ClusterIP en el puerto del protocolo de red. El entorno de su contenedor lleva la conexión compuesta a partir de la arista hacia el backend — el nombre del Service interno del clúster del backend, el usuario y la base de datos, sin contraseña en la URL — y mantiene el listener de depuración de FerretDB en la dirección de loopback del pod, donde ningún otro pod lo alcanza:

env:
- name: FERRETDB_LISTEN_ADDR
value: :27017
- name: FERRETDB_DEBUG_ADDR
value: 127.0.0.1:8088
- name: FERRETDB_POSTGRESQL_URL
value: postgres://postgres@database-zdbackend-default:5432/postgres
- name: PGPASSWORD
value: apppass

Ninguna de las dos sondas necesita ese listener. La sonda de readiness ejecuta ferretdb ping dentro del contenedor, que hace ping al puerto del protocolo de red y así también demuestra la conexión con el backend; la sonda de liveness solo comprueba que el puerto del protocolo de red acepte conexiones, así que una caída del backend saca el proxy de su Service sin reiniciarlo:

livenessProbe:
tcpSocket:
port: 27017
readinessProbe:
exec:
command:
- /ferretdb
- ping

El backend se renderiza como un StatefulSet con un volumen persistente montado en /var/lib/postgresql/data, más un Service ClusterIP y un Service headless.