Stack FerretDB — un database documentale composto come modulo
Questo esempio compila uno stack piccolo e reale — un database documentale che espone il protocollo di rete di MongoDB — in manifest Kubernetes sintetizzati a partire da un unico Aggregate scritto dallo sviluppatore.
Il database documentale non è un singolo componente. È un modulo: un sotto-aggregato riutilizzabile che compone due componenti a carico di lavoro singolo —
- un proxy che parla il protocollo di rete di MongoDB e non mantiene alcuno stato locale, e
- un backend, PostgreSQL 17 con l’estensione DocumentDB, che rende persistenti i dati su un volume.
Il modulo cabla il proprio arco interno dal proxy al backend ed esporta il proxy come suo endpoint pubblico mongo. L’Aggregate di primo livello importa il modulo per nome e renderizza lo stack composto; l’operatore dimensiona i componenti interni del modulo nella Release.
File
| File | Ruolo |
|---|---|
aggregate.yaml | Intento dello sviluppatore: importa il modulo di database documentale (core/ferretdb). |
manifest-helm-synth.yaml | Mappa i tipi proxy e backend alle rispettive Recipes helm synth. |
release-helm-synth.yaml | Documento dell’operatore per il target Kubernetes. Dimensiona i componenti interni del modulo tramite i loro ID con ambito di modulo; tutto ciò che è lasciato ai valori predefiniti dello schema viene renderizzato in modo autonomo. |
Che cosa dimostra
- Composizione come modulo. Una capacità a più carichi di lavoro — un database documentale che in realtà è un proxy più un backend di storage — è confezionata come un sotto-aggregato che compone due componenti a carico di lavoro singolo, non come un unico componente monolitico. Il modulo viene importato per nome e riutilizzato ovunque serva un database documentale.
- Un arco interno al modulo. Il proxy dichiara un uso del backend; host, porta, utente e database dei
providesdella Recipe del backend vengono convogliati nel proxy e composti nella sua connessione PostgreSQL. Il compilatore instrada le stringhe senza interpretarle. - Un endpoint pubblico. Il modulo esporta il suo proxy come
mongo, il nome pubblico stabile a cui si connette un consumatore di database documentale — disaccoppiato dai nomi dei componenti interni del modulo. - Dimensionamento dei componenti interni da parte dell’operatore. La Release indirizza i componenti interni del modulo tramite i loro ID con ambito di modulo (
database.backend,database.proxy) per impostarne le risorse di calcolo, senza che l’Aggregate dello sviluppatore ripeta il dimensionamento fisico. - Una credenziale condivisa. Il proxy delega l’autenticazione al suo backend PostgreSQL, quindi i due condividono un’unica password. Questo esempio usa un valore predefinito di sviluppo condiviso e scritto inline, così lo stack funziona in modo autonomo senza alcun segreto esterno.
- Una stringa di connessione senza password. L’URL di connessione PostgreSQL del proxy viene renderizzato senza la password incorporata; la password viene fornita separatamente tramite la variabile d’ambiente standard di libpq
PGPASSWORD, che il driver unisce alla connessione. In questo modo la credenziale resta fuori dalla stringa di connessione nel manifest renderizzato. - Immagini riproducibili. Sia il proxy sia il backend fissano tag di immagine espliciti, quindi i manifest renderizzati fanno riferimento a immagini stabili.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example ferretdb-stackPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd ferretdb-stackBuild
Questo workspace non contiene alcun .aggrega-config.yaml, quindi le entità della libreria standard vengono risolte dal registry dell’hub, hub.aggrega.ai, e non serve alcun flag di catalogo; --auto-pull scrive durante il build il lockfile che manca a un clone appena creato:
aggrega build --release release-helm-synth.yaml --auto-pullGli artefatti renderizzati finiscono sotto dist/. Il target Kubernetes renderizza manifest semplici offline — non è richiesto alcun pull di chart.
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella dell’area di lavoro non contiene ancora una cartella `ferretdb-stack`, chiama una volta lo strumento `scaffold` con `example` impostato a `ferretdb-stack` e senza `dir`: scrive l’esempio in una nuova cartella `ferretdb-stack`. Poi chiama lo strumento `build` con `workspace_root` impostato a `ferretdb-stack`, `release` impostato a `release-helm-synth.yaml`, `auto_pull` impostato a true e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `ferretdb-stack/dist/`.Come appare lo stack composto
Il proxy viene renderizzato come un Deployment stateless più un Service ClusterIP sulla porta del protocollo di rete. L’ambiente del suo container porta la connessione composta dall’arco verso il backend — il nome del Service interno al cluster del backend, l’utente e il database, senza alcuna password nell’URL — e mantiene il listener di debug di FerretDB sull’indirizzo di loopback del pod, dove nessun altro pod lo raggiunge:
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: apppassNessuna delle due probe ha bisogno di quel listener. La readiness probe esegue ferretdb ping all’interno del container, che invia un ping alla porta del protocollo di rete e quindi verifica anche la connessione al backend; la liveness probe controlla solo che la porta del protocollo di rete accetti connessioni, quindi un’interruzione del backend toglie il proxy dal suo Service senza riavviarlo:
livenessProbe: tcpSocket: port: 27017readinessProbe: exec: command: - /ferretdb - pingIl backend viene renderizzato come uno StatefulSet con un volume persistente montato in /var/lib/postgresql/data, più un Service ClusterIP e un Service headless.