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

Une base de données managée et le service qui la lit, sur Terraform et CloudFormation

Un Aggregate contient une base de données PostgreSQL et le serveur qui la lit. Le même Aggregate est construit de trois façons pour AWS : comme une seule configuration racine Terraform, la base de données étant provisionnée par le module RDS publié du projet terraform-aws-modules et le serveur exécuté comme service Amazon ECS sur Fargate ; comme une seule stack CloudFormation contenant les deux ; et comme deux stacks CloudFormation, la base de données dans l’une et le serveur dans l’autre.

Sur chaque cible, le serveur reçoit l’adresse de la base de données sous la forme que cette cible résout elle-même : une référence à une sortie de module dans la configuration racine, un Fn::GetAtt à l’intérieur d’une seule stack, un Fn::ImportValue entre deux. Le compilateur n’en évalue aucune. L’adresse n’existe pas tant que l’instance n’est pas créée, si bien que le build transmet une référence sans la résoudre et que la cible la résout lors du déploiement.

Les blocs de sortie de cette page sont copiés d’une exécution réelle, conformément à Lire la sortie sur ces pages.

Fichiers

  • aggregate.yaml — l’intention du développeur : un composant db de type core/datastore/postgres avec une base de données logique orders dont le propriétaire est le rôle orders_admin, et un composant api de type core/compute/server qui l’utilise. Aucune clé ni valeur qu’il contient ne concerne AWS.
  • manifest-terraform.yaml — lie la base de données à la Recipe terraform/postgres-rds-terraform-aws-modules, le serveur à terraform/server-ecs et la Feature core/backup à terraform/backup-native.
  • manifest-cloudformation.yaml — lie la base de données à cloudformation/postgres-rds, le serveur à cloudformation/server-ecs et la Feature core/backup à cloudformation/backup-native.
  • release-terraform.yaml — les deux composants dans une seule frontière, construits via le Manifest Terraform.
  • release-one-stack.yaml — les deux composants dans une seule frontière, construits via le Manifest CloudFormation, si bien que les deux s’assemblent en une seule stack.
  • release-two-stacks.yaml — la même intention répartie sur deux frontières, si bien que la référence du serveur à la base de données franchit une limite de stack.
  • .aggrega-config.yaml — nomme le registre du hub depuis lequel se résout le catalogue de la bibliothèque standard.

Les entités qu’utilise cet exemple se trouvent toutes dans ce catalogue. Rien n’est copié à côté des fichiers de release.

Ce que demande le serveur

Le serveur déclare une arête, sur un socket qu’il nomme database, et demande quatre des entrées que publie la base de données, sous les noms de variables d’environnement que lit sa propre configuration :

api:
type: core/compute/server
uses:
database:
db:
target: db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
- in: DB_USER
from: user
- in: DB_NAME
from: database

core/compute/server ne déclare aucun socket qui lui soit propre, si bien que database est un socket ad hoc : l’arête ne porte aucun sélecteur ni aucune liste d’autorisation d’inject, et chaque clé from: doit tout de même être une clé que publie la base de données — voir adhoc-uses-socket pour ce contrat. L’Aggregate ne nomme jamais une adresse, un numéro de port ou un fournisseur de cloud, et c’est le même fichier pour les trois builds ci-dessous.

Ce que fournit l’opérateur

Chaque Release nomme, sous infra.overrides, des éléments que l’opérateur exécute déjà et que lisent les Recipes : le groupe de sous-réseaux de base de données RDS et les groupes de sécurité de la base de données, ainsi que le cluster ECS, les sous-réseaux et les groupes de sécurité auxquels les tâches se rattachent, et le rôle d’exécution avec lequel ECS récupère l’image et écrit les journaux. L’image du serveur est infra.image. Les deux Recipes du serveur exigent l’image, le cluster, les sous-réseaux, les groupes de sécurité et le rôle d’exécution, et la Recipe Terraform de la base de données exige le groupe de sous-réseaux : un build auquel il en manque un s’arrête en nommant la clé, plutôt que de choisir un réseau ou un rôle à votre place.

Chacune de ces valeurs est un espace réservé — 123456789012 est le numéro de compte que la documentation AWS utilise dans ses exemples, et example-cluster, example-private-db-subnets, les ID subnet-… et sg-…, le rôle et registry.example.com/orders-api:1.0.0 représentent des ressources de votre propre compte. Le build les accepte parce qu’il ne les recherche jamais ; remplacez-les avant de planifier ou de déployer.

Les Recipes Terraform lisent leurs clés dans l’orthographe terraform du catalogue (subnet_group, subnet_ids, vpc_security_groups, cluster, execution_role_arn) ; les Recipes CloudFormation les lisent sous les noms propres des propriétés des ressources (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), si bien que les mêmes valeurs de l’opérateur s’écrivent différemment sur les deux cibles.

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 :

Terminal window
aggrega scaffold --example aws-rds-and-ecs-service

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd aws-rds-and-ecs-service

Build

Cet exemple fournit trois releases, nommez donc celle que vous voulez. Une seule release est construite par exécution. Dans une copie neuve, passez --auto-pull la première fois que chaque release est construite, afin que son lockfile soit rempli pendant le build. Le premier build Terraform récupère le module RDS depuis son dépôt git, au commit qu’enregistre l’épinglage propre à la Recipe :

Terminal window
aggrega build --release release-terraform.yaml --auto-pull

Il affiche, <workspace> désignant le dossier de cet exemple :

Pull complete: release-terraform.lock (entities=11, source_artifacts=1, external_inputs=0)
Total build time: 9.4s
Build completed: 151 files written to <workspace>/dist

Une fois le lockfile créé, la commande simple effectue le build avec lui :

Terminal window
aggrega build --release release-terraform.yaml
Total build time: 5.7s
Build completed: 151 files written to <workspace>/dist

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 `aws-rds-and-ecs-service`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `aws-rds-and-ecs-service` et sans `dir` : il écrit l’exemple dans un nouveau dossier `aws-rds-and-ecs-service`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `aws-rds-and-ecs-service`, `release` défini sur `release-terraform.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `aws-rds-and-ecs-service/dist/`.

Une seule configuration racine Terraform

La configuration racine de la frontière se trouve dans dist/one-root/terraform/aggrega.modules.tf, et les fichiers propres à chaque composant se trouvent dans le répertoire que vise son bloc module : le module RDS copié localement sous modules/db/, et le module ECS du serveur, conservé à côté de sa Recipe dans le catalogue, sous modules/api/. Toute la configuration racine :

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "api" {
source = "./modules/api"
assign_public_ip = false
cluster = "example-cluster"
cpu = "256"
desired_count = 2
environment = {"DB_HOST":"${module.db.db_instance_address}","DB_NAME":"orders","DB_PORT":"5432","DB_USER":"orders_admin"}
execution_role_arn = "arn:aws:iam::123456789012:role/example-ecs-task-execution"
image = "registry.example.com/orders-api:1.0.0"
memory = "512"
name = "api"
port = 8080
security_groups = ["sg-0fedcba9876543210"]
subnet_ids = ["subnet-0123456789abcdef0","subnet-0fedcba9876543210"]
}
module "db" {
source = "./modules/db"
allocated_storage = 50
backup_retention_period = 14
create_db_subnet_group = false
db_name = "orders"
db_subnet_group_name = "example-private-db-subnets"
engine = "postgres"
engine_version = "16"
family = "postgres16"
identifier = "db"
instance_class = "db.t3.small"
manage_master_user_password = true
multi_az = true
port = "5432"
skip_final_snapshot = false
storage_type = "gp3"
username = "orders_admin"
vpc_security_group_ids = ["sg-0123456789abcdef0"]
}

L’argument environment du serveur porte les quatre valeurs que l’arête a demandées. DB_HOST vaut ${module.db.db_instance_address} : la Recipe de la base de données publie une référence à la sortie db_instance_address propre au module RDS via l’appel de module que cette même racine déclare comme module "db", si bien que Terraform l’évalue ici, au moment du plan et de l’apply, et que le module du serveur reçoit l’adresse de l’instance comme une entrée ordinaire. Les trois autres sont du texte brut que le compilateur connaissait à l’avance — le port que configure la Release et les deux noms qu’a écrits l’Aggregate.

Cela fonctionne parce que la Recipe du serveur est une Recipe source: : son mappage devient les arguments du bloc module du serveur, qui est la seule position que Terraform évalue dans une portée où le module voisin est déclaré — voir Consommer la valeur publiée d’un autre composant et Une paire détaillée pour la mécanique, et pour ce qui se passe mal lorsqu’un consommateur écrit la référence ailleurs. Pour la même raison, planifiez ce répertoire — celui qui contient aggrega.modules.tf — plutôt que l’un ou l’autre des répertoires de module isolément.

Sur une copie de travail de ce répertoire, tofu init -backend=false charge depuis le disque la racine et les modules copiés localement et ne récupère que les fournisseurs :

Initializing modules...
- api in modules/api
- db in modules/db
- db.db_instance in modules/db/modules/db_instance
- db.db_instance_role_association in modules/db/modules/db_instance_role_association
- db.db_option_group in modules/db/modules/db_option_group
- db.db_parameter_group in modules/db/modules/db_parameter_group
- db.db_subnet_group in modules/db/modules/db_subnet_group
[… omitted: provider installation, whose versions move with the registry, and OpenTofu's closing advice]

et tofu validate affiche ensuite :

Success! The configuration is valid.

Une seule stack CloudFormation

Terminal window
aggrega build --release release-one-stack.yaml --auto-pull
Pull complete: release-one-stack.lock (entities=11, source_artifacts=0, external_inputs=0)
Total build time: 6.2s
Build completed: 1 file written to <workspace>/dist

La stack assemblée se trouve dans dist/one-stack/cloudformation/cloudformation-stack.json et contient trois ressources : Db, l’instance RDS ; Api, le service ECS ; et ApiTaskDefinition, la définition de tâche qu’il exécute. L’environnement du conteneur dans ApiTaskDefinition :

"Environment": [
{
"Name": "DB_HOST",
"Value": {
"Fn::GetAtt": [
"Db",
"Endpoint.Address"
]
}
},
{
"Name": "DB_NAME",
"Value": "orders"
},
{
"Name": "DB_PORT",
"Value": "5432"
},
{
"Name": "DB_USER",
"Value": "orders_admin"
}
],

DB_HOST est un Fn::GetAtt sur l’Endpoint.Address de l’instance, rapporté à l’ID logique Db que la Recipe de la base de données dérive du nom de composant db. CloudFormation le résout lorsqu’il crée la stack, et comme la définition de tâche du serveur lit un attribut de Db, il crée l’instance en premier. Voir Références au sein d’une stack.

Deux stacks CloudFormation

Terminal window
aggrega build --release release-two-stacks.yaml --auto-pull
Pull complete: release-two-stacks.lock (entities=11, source_artifacts=0, external_inputs=0)
Total build time: 6.2s
Build completed: 2 files written to <workspace>/dist

Rien ne change dans aggregate.yaml. La Release place la base de données dans la frontière data et le serveur dans la frontière app, si bien que chacun s’assemble en une stack qui lui est propre, et l’arête du serveur vers la base de données passe d’une stack à l’autre. La stack de la base de données, dist/two-stacks-data/cloudformation/cloudformation-stack.json, publie chaque entrée que consomme l’arête comme une sortie avec un Export. Ses Outputs :

"Outputs": {
"dbXXdatabase": {
"Value": "orders",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--database"
}
},
"dbXXhost": {
"Value": {
"Fn::GetAtt": [
"Db",
"Endpoint.Address"
]
},
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--host"
}
},
"dbXXport": {
"Value": "5432",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--port"
}
},
"dbXXprotocol": {
"Value": "postgres"
},
"dbXXuser": {
"Value": "orders_admin",
"Export": {
"Name": "aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--user"
}
}
},

protocol est publié aussi, et ne porte aucun Export parce qu’aucune arête ne le lit. La stack du serveur, dist/two-stacks-app/cloudformation/cloudformation-stack.json, relit chacune des quatre sous le même nom :

"Environment": [
{
"Name": "DB_HOST",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--host"}
},
{
"Name": "DB_NAME",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--database"}
},
{
"Name": "DB_PORT",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--port"}
},
{
"Name": "DB_USER",
"Value": {"Fn::ImportValue":"aggrega--orders-two-stacks--two-stacks-data-zscloudformation--db--user"}
}
],

Chaque nom d’export joint le nom de la Release, le répertoire de sortie de la frontière productrice, le composant et l’entrée, si bien qu’il est fixé au moment du build et que le consommateur peut le nommer avant que l’une ou l’autre stack existe. Aucune Release ici ne déclare de compte ni de région, si bien que la lecture est un Fn::ImportValue dans le même compte. La façon dont le nom est construit, et le cas où le consommateur lit plutôt entre comptes, sont exposés dans Câblage entre stacks. Un import ne se résout que contre un export qui existe déjà, si bien que la stack de la base de données est créée avant celle du serveur ; ordonner les deux stacks revient à l’opérateur, en dehors du build.

Le mot de passe appartient à RDS

L’Aggregate nomme l’utilisateur de la base de données et rien de son mot de passe, et aucune Release ne rattache d’information d’identification à la base de données. Sur les deux cibles, la Recipe que sélectionne le Manifest confie le mot de passe à RDS : manage_master_user_password = true sur le bloc de module ci-dessus, et ManageMasterUserPassword sur l’instance dans chaque stack. Les Properties de la base de données dans le template à une seule stack :

"Properties": {
"AllocatedStorage": 50,
"BackupRetentionPeriod": 14,
"DBInstanceClass": "db.t3.small",
"DBName": "orders",
"DBSubnetGroupName": "example-private-db-subnets",
"Engine": "postgres",
"EngineVersion": "16",
"ManageMasterUserPassword": true,
"MasterUsername": "orders_admin",
"MultiAZ": true,
"Port": 5432,
"StorageType": "gp3",
"VPCSecurityGroups": [
"sg-0123456789abcdef0"
]
},

RDS génère le mot de passe administrateur lorsqu’il crée l’instance et le conserve dans AWS Secrets Manager. Aucune entrée du build ne porte de mot de passe, si bien qu’aucun des trois builds n’en écrit un dans un fichier. Le serveur reçoit le nom de l’utilisateur et non son mot de passe ; lire le mot de passe depuis Secrets Manager est laissé au code qu’exécute l’image du serveur.

La sauvegarde est un rattachement

RDS sauvegarde lui-même l’instance et conserve chaque sauvegarde automatisée pendant 7 jours lorsque rien n’indique le contraire. Chaque Release les conserve pendant 14 jours en rattachant core/backup à la base de données, dans son entrée pour db :

db:
features:
backup:
type: core/backup
infra:
retention_days: 14

Chaque Manifest lie la Feature à la FeatureRecipe de sa cible, terraform/backup-native ou cloudformation/backup-native, et aucune des deux ne rend quoi que ce soit : la sauvegarde est un paramètre de l’instance, si bien que la Recipe de la base de données lit le rattachement et écrit la rétention là où l’instance est écrite — backup_retention_period = 14 sur le bloc de module, et "BackupRetentionPeriod": 14 dans les Properties de l’instance ci-dessus. C’est pourquoi le template à une seule stack contient exactement trois ressources.

Construire n’est pas déployer

Chaque build écrit des fichiers sous dist/ et s’arrête. Il n’exécute jamais Terraform, OpenTofu ni CloudFormation, ne s’authentifie jamais auprès d’AWS et ne recherche aucun des identifiants que nomment les Releases. Planifier et appliquer la configuration racine, et créer les stacks, sont des étapes que vous effectuez sur la sortie, avec vos propres informations d’identification, après avoir remplacé les espaces réservés.

Entrée identique, sortie identique

Construire deux fois à partir d’entrées inchangées produit une sortie identique octet pour octet, pour chacune des trois releases. Le compilateur ne résout aucune donnée en direct, si bien qu’une reconstruction n’a rien à découvrir qui puisse déplacer les octets. C’est la propriété sur laquelle repose une revue fondée sur les diffs.

dist/, .aggrega/ et les fichiers *.lock sont générés et ne sont pas commités ; ils se régénèrent à partir des fichiers qui le sont.