Stack FerretDB — une base de données documentaire composée comme un module
Cet exemple compile une petite stack réelle — une base de données documentaire exposant le protocole réseau de MongoDB — en manifestes Kubernetes synthétisés à partir d’un seul Aggregate écrit par le développeur.
La base de données documentaire n’est pas un composant unique. C’est un module : un sous-agrégat réutilisable qui compose deux composants à charge de travail unique —
- un proxy qui parle le protocole réseau de MongoDB et ne conserve aucun état local, et
- un backend, PostgreSQL 17 avec l’extension DocumentDB, qui persiste les données sur un volume.
Le module câble sa propre arête interne du proxy vers le backend et exporte le proxy comme son endpoint public mongo. L’Aggregate de plus haut niveau importe le module par son nom et rend la stack composée ; l’opérateur dimensionne les composants internes du module dans la Release.
Fichiers
| Fichier | Rôle |
|---|---|
aggregate.yaml | Intention du développeur : importe le module de base de données documentaire (core/ferretdb). |
manifest-helm-synth.yaml | Associe les types proxy et backend à leurs Recipes helm synth. |
release-helm-synth.yaml | Enregistrement de l’opérateur pour la cible Kubernetes. Dimensionne les composants internes du module par leurs ID à portée de module ; tout ce qui est laissé aux valeurs par défaut du schéma est rendu de manière autonome. |
Ce qu’il démontre
- Composition en module. Une capacité à plusieurs charges de travail — une base de données documentaire qui est en réalité un proxy plus un backend de stockage — est empaquetée comme un sous-agrégat composant deux composants à charge de travail unique, et non comme un composant monolithique. Le module est importé par son nom et réutilisé partout où une base de données documentaire est nécessaire.
- Une arête interne au module. Le proxy déclare une utilisation du backend ; l’hôte, le port, l’utilisateur et la base de données des
providesde la Recipe du backend sont acheminés dans le proxy et composés en sa connexion PostgreSQL. Le compilateur achemine les chaînes sans les interpréter. - Un endpoint public. Le module exporte son proxy sous le nom
mongo, le nom public stable auquel se connecte un consommateur de base de données documentaire — découplé des noms des composants internes du module. - Dimensionnement des composants internes par l’opérateur. La Release adresse les composants internes du module par leurs ID à portée de module (
database.backend,database.proxy) pour définir les ressources de calcul, sans que l’Aggregate du développeur ne reprenne le dimensionnement physique. - Une information d’identification partagée. Le proxy délègue l’authentification à son backend PostgreSQL, si bien que les deux partagent un seul mot de passe. Cet exemple utilise une valeur par défaut de développement partagée et écrite en ligne, si bien que la stack s’exécute de manière autonome sans aucun secret externe.
- Une chaîne de connexion sans mot de passe. L’URL de connexion PostgreSQL du proxy est rendue sans le mot de passe intégré ; le mot de passe est fourni séparément par la variable d’environnement libpq standard
PGPASSWORD, que le pilote fusionne dans la connexion. Cela maintient l’information d’identification hors de la chaîne de connexion dans le manifeste rendu. - Images reproductibles. Le proxy comme le backend épinglent des tags d’image explicites, si bien que les manifestes rendus référencent des images stables.
Générer l’exemple
Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.
Écrivez l’exemple dans un nouveau dossier qui porte son nom :
aggrega scaffold --example ferretdb-stackElle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :
cd ferretdb-stackBuild
Ce workspace ne contient aucun .aggrega-config.yaml, si bien que les entités de la bibliothèque standard sont résolues depuis le registre du hub, hub.aggrega.ai, et aucune option de catalogue n’est nécessaire ; --auto-pull écrit pendant le build le lockfile qui manque à un clone récent :
aggrega build --release release-helm-synth.yaml --auto-pullLes artefacts rendus atterrissent sous dist/. La cible Kubernetes rend des manifestes simples hors ligne — aucun pull de chart n’est requis.
Avec un assistant IA
Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.
Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `ferretdb-stack`, appelez une fois l’outil `scaffold` avec `example` défini sur `ferretdb-stack` et sans `dir` : il écrit l’exemple dans un nouveau dossier `ferretdb-stack`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `ferretdb-stack`, `release` défini sur `release-helm-synth.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi les fichiers écrits par le build ; ils se trouvent sous `ferretdb-stack/dist/`.À quoi ressemble la stack composée
Le proxy est rendu sous forme d’un Deployment sans état plus un Service ClusterIP sur le port du protocole réseau. L’environnement de son conteneur porte la connexion composée à partir de l’arête vers le backend — le nom du Service interne au cluster du backend, l’utilisateur et la base de données, sans mot de passe dans l’URL — et maintient l’écouteur de débogage de FerretDB sur l’adresse de bouclage du pod, où aucun autre pod ne l’atteint :
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: apppassAucune des deux sondes n’a besoin de cet écouteur. La sonde de readiness exécute ferretdb ping dans le conteneur, qui envoie un ping au port du protocole réseau et prouve donc aussi la connexion au backend ; la sonde de liveness vérifie seulement que le port du protocole réseau accepte des connexions, si bien qu’une panne du backend retire le proxy de son Service sans le redémarrer :
livenessProbe: tcpSocket: port: 27017readinessProbe: exec: command: - /ferretdb - pingLe backend est rendu sous forme d’un StatefulSet avec un volume persistant monté sur /var/lib/postgresql/data, plus un Service ClusterIP et un Service headless.