Les fichiers d’un build
Cette page explique une seule idée, quel fichier d’un build dit quoi, et n’est pas un espace de travail exécutable. Une application web avec PostgreSQL, construite une étape à la fois la montre dans un espace de travail que vous construisez ; écrivez-le dans un dossier à vous avec :
aggrega scaffold --example quickstart-webElle affiche ensuite les prochaines commandes à exécuter :
cd quickstart-webcd 1aggrega build --release release.yaml --auto-pullexport QUICKSTART_DB_PASSWORD=choose-a-passworddocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait# then open http://127.0.0.1:8080/ in your browserCinq types de fichier, chacun avec un seul auteur
Un build lit cinq types de fichier. Chacun dit une seule chose et, dans une équipe typique, chacun a son propre auteur :
- un Component dit ce qu’est un type de composant : les valeurs qu’un développeur peut définir, les paramètres d’infrastructure qu’un opérateur peut définir, ce qu’il publie vers les composants qui s’y connectent, et les sockets par lesquels il se connecte. Le catalogue de la bibliothèque standard fournit les Components dont la plupart des applications ont besoin, comme
core/datastore/postgresetcore/compute/server, de sorte qu’un espace de travail n’en écrit généralement aucun ; - un Aggregate appartient au développeur : quels composants l’application possède, et à quoi chacun se connecte ;
- une Recipe transforme un type de composant en fichiers pour un outil — un service Compose, un chart Helm, un module Terraform ;
- un Manifest choisit quelle Recipe réalise chaque type de composant pour une cible ;
- une Release nomme un Aggregate et un Manifest et fournit les paramètres d’un environnement. C’est ce que vous construisez :
aggrega build --release release.yaml.
Cette répartition est une recommandation : une seule personne peut écrire les cinq, et le build accepte chacun d’eux du moment qu’il est valide.
L’Aggregate : les composants et leurs connexions
La première étape de l’exemple est une application web et sa base de données. Son Aggregate, tiré de 1/aggregate.yaml sans ses commentaires :
spec: components: web: type: core/compute/server features: db_password: type: core/secret-value values: key: PGPASSWORD origin: "${QUICKSTART_DB_PASSWORD}" uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: database
db: type: core/datastore/postgres features: password: type: core/secret-value values: key: POSTGRES_PASSWORD origin: "${QUICKSTART_DB_PASSWORD}"Rien ici ne nomme un port, un hôte, un namespace ou un outil. web se connecte à db par son socket database, et la liste inject indique quelle variable de l’application reçoit chaque entrée que publie la base de données : from: nomme l’entrée, in: la variable.
Une connexion est une chaîne, acheminée
La Recipe de la base de données publie host, port, user et database pour que la connexion les lise. L’adresse que contient host dépend de la Recipe que le Manifest a choisie : le nom d’un service lorsque la base de données s’exécute à côté de l’application, une chaîne pointeur qu’un outil de provisionnement résout pour une base de données gérée, ou l’adresse d’un serveur qui existe déjà. Le build copie chaque chaîne publiée dans la variable nommée par l’Aggregate et ne l’interprète pas : il ne résout jamais une adresse et ne vérifie jamais qu’elle est joignable.
Le Manifest et la Release
Le Manifest, tiré de 1/manifest.yaml, lie chaque type de composant, ainsi que les rattachements de mots de passe, à la Recipe qui le réalise sur Docker Compose :
spec: mappings: components: type: core/compute/server:1.1.0: compose/server:2.0.0 core/datastore/postgres:1.0.0: compose/postgres:1.0.0 features: type: core/secret-value:1.0.0: compose/dotenv-secret:1.0.0La Release, tirée de 1/release.yaml, nomme l’Aggregate et le Manifest et fournit ce que seul un environnement connaît, ici l’image qu’exécute l’application, le port sur lequel elle écoute et le port sur lequel Docker Compose la publie, sur l’adresse de bouclage de votre machine (le digest de l’image abrégé) :
spec: aggregate: quickstart-web manifest: quickstart-web-compose components: web: infra: image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:… port: 8080 published_port: 8080 db: {}Les étapes suivantes de l’exemple l’étendent : un cache Redis à côté de la base de données, puis les mêmes composants sur AWS via Terraform, puis les sauvegardes de la base de données.
Paramètres : un seul Aggregate, de nombreux environnements
Une valeur qui diffère d’un environnement à l’autre est déclarée dans l’Aggregate comme paramètre typé, référencée là où elle est utilisée, et fournie par chaque Release. Dans Une tâche exécutée à la demande, l’Aggregate déclare la planification de son rapport :
spec: parameters: report_schedule: type: string default: "" components: report: type: core/compute/task values: schedule: "{{ .parameters.report_schedule }}"et une Release le renseigne :
spec: parameters: report_schedule: "30 2 * * 1-5"Le build vérifie chaque valeur que fournit une Release par rapport au type du paramètre avant de remplir le modèle. Une Release n’écrit jamais elle-même les values d’un composant : elle renseigne les paramètres qu’expose l’Aggregate, de sorte que l’Aggregate reste le seul endroit qui dit quelles valeurs varient selon l’environnement. Une Release peut aussi lire ses paramètres depuis un fichier qui leur est propre, parameters: { $import: ./env/prod-values.yaml }.