Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

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 :

Terminal window
aggrega scaffold --example quickstart-web

Elle affiche ensuite les prochaines commandes à exécuter :

Terminal window
cd quickstart-web
cd 1
aggrega build --release release.yaml --auto-pull
export QUICKSTART_DB_PASSWORD=choose-a-password
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait
# then open http://127.0.0.1:8080/ in your browser

Cinq 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/postgres et core/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.0

La 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 }.