Eine verwaltete Datenbank und der Service, der sie liest, auf Terraform und CloudFormation
Ein Aggregate enthält eine PostgreSQL-Datenbank und den Server, der sie liest. Dasselbe Aggregate wird auf drei Arten für AWS gebaut: als eine Terraform-Root-Konfiguration, wobei die Datenbank über das veröffentlichte RDS-Modul des Projekts terraform-aws-modules bereitgestellt wird und der Server als Amazon-ECS-Service auf Fargate läuft; als ein CloudFormation-Stack, der beide enthält; und als zwei CloudFormation-Stacks, die Datenbank im einen und der Server im anderen.
Auf jedem Ziel erhält der Server die Adresse der Datenbank in der Form, die dieses Ziel selbst auflöst: eine Referenz auf eine Modulausgabe in der Root-Konfiguration, ein Fn::GetAtt innerhalb eines Stacks, ein Fn::ImportValue über zwei hinweg. Der Compiler wertet keine davon aus. Die Adresse existiert erst, wenn die Instanz erstellt ist, daher leitet der Build eine Referenz unaufgelöst weiter, und das Ziel löst sie bei der Bereitstellung auf.
Die Ausgabeblöcke auf dieser Seite sind aus einem echten Lauf kopiert, gemäß Die Ausgabe auf diesen Seiten lesen.
Dateien
aggregate.yaml— Entwicklerabsicht: eine Komponentedbvom Typcore/datastore/postgresmit einer logischen Datenbankorders, deren Eigentümer die Rolleorders_administ, und eine Komponenteapivom Typcore/compute/server, die sie verwendet. Kein Schlüssel und kein Wert darin betrifft AWS.manifest-terraform.yaml— bindet die Datenbank an das Recipeterraform/postgres-rds-terraform-aws-modules, den Server anterraform/server-ecsund das Featurecore/backupanterraform/backup-native.manifest-cloudformation.yaml— bindet die Datenbank ancloudformation/postgres-rds, den Server ancloudformation/server-ecsund das Featurecore/backupancloudformation/backup-native.release-terraform.yaml— beide Komponenten in einer Boundary, gebaut über das Terraform-Manifest.release-one-stack.yaml— beide Komponenten in einer Boundary, gebaut über das CloudFormation-Manifest, sodass beide zu einem einzigen Stack zusammengesetzt werden.release-two-stacks.yaml— dieselbe Absicht, auf zwei Boundaries aufgeteilt, sodass die Referenz des Servers auf die Datenbank eine Stack-Grenze überquert..aggrega-config.yaml— nennt die Hub-Registry, aus der der Katalog der Standardbibliothek aufgelöst wird.
Die Entitäten, die dieses Beispiel verwendet, liegen alle in diesem Katalog. Neben die Release-Dateien wird nichts hineinkopiert.
Was der Server anfordert
Der Server deklariert eine Kante an einem Socket, den er database nennt, und fordert vier der Einträge an, die die Datenbank veröffentlicht, unter den Namen der Umgebungsvariablen, die seine eigene Konfiguration liest:
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: databasecore/compute/server deklariert keinen eigenen Socket, daher ist database ein Ad-hoc-Socket: Die Kante trägt keinen Selektor und keine Inject-Allowlist, und jeder from:-Schlüssel muss dennoch einer sein, den die Datenbank veröffentlicht — siehe adhoc-uses-socket für diesen Vertrag. Das Aggregate nennt nie eine Adresse, eine Portnummer oder einen Cloud-Anbieter, und es ist für alle drei Builds unten dieselbe Datei.
Was der Operator liefert
Jedes Release nennt unter infra.overrides Dinge, die der Operator bereits betreibt und die die Recipes lesen: die RDS-DB-Subnetzgruppe und die Sicherheitsgruppen der Datenbank sowie den ECS-Cluster, die Subnetze und Sicherheitsgruppen, an die die Tasks angebunden werden, und die Ausführungsrolle, mit der ECS das Image abruft und Logs schreibt. Das Image des Servers ist infra.image. Beide Server-Recipes verlangen das Image, den Cluster, die Subnetze, die Sicherheitsgruppen und die Ausführungsrolle, und das Terraform-Datenbank-Recipe verlangt die Subnetzgruppe: Ein Build, dem eines davon fehlt, bricht ab und nennt den Schlüssel, statt für Sie ein Netzwerk oder eine Rolle zu wählen.
Jeder dieser Werte ist ein Platzhalter — 123456789012 ist die Kontonummer, die die AWS-Dokumentation in Beispielen verwendet, und example-cluster, example-private-db-subnets, die IDs subnet-… und sg-…, die Rolle und registry.example.com/orders-api:1.0.0 stehen für Ressourcen in Ihrem eigenen Konto. Der Build akzeptiert sie, weil er sie nie nachschlägt; ersetzen Sie sie, bevor Sie planen oder bereitstellen.
Die Terraform-Recipes lesen ihre Schlüssel in der Terraform-Schreibweise des Katalogs (subnet_group, subnet_ids, vpc_security_groups, cluster, execution_role_arn); die CloudFormation-Recipes lesen sie unter den eigenen Namen der Ressourceneigenschaften (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), daher werden dieselben Werte des Operators auf den beiden Zielen unterschiedlich geschrieben.
Das Beispiel generieren
Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example aws-rds-and-ecs-serviceDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd aws-rds-and-ecs-serviceBuild
Dieses Beispiel liefert drei Releases mit, nennen Sie also das gewünschte. Pro Lauf wird ein Release gebaut. Übergeben Sie in einer frischen Kopie --auto-pull, wenn ein Release zum ersten Mal gebaut wird, damit sein Lockfile während des Builds befüllt wird. Der erste Terraform-Build ruft das RDS-Modul aus seinem Git-Repository ab, an dem Commit, den die eigene Fixierung des Recipe festhält:
aggrega build --release release-terraform.yaml --auto-pullEr gibt aus, wobei <workspace> für den Ordner dieses Beispiels steht:
Pull complete: release-terraform.lock (entities=11, source_artifacts=1, external_inputs=0)Total build time: 9.4sBuild completed: 151 files written to <workspace>/distSobald das Lockfile existiert, baut der einfache Befehl dagegen:
aggrega build --release release-terraform.yamlTotal build time: 5.7sBuild completed: 151 files written to <workspace>/distMit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.
Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `aws-rds-and-ecs-service` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `aws-rds-and-ecs-service` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `aws-rds-and-ecs-service`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `aws-rds-and-ecs-service`, `release` auf `release-terraform.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `aws-rds-and-ecs-service/dist/`.Eine Terraform-Root-Konfiguration
Die Root-Konfiguration der Boundary landet unter dist/one-root/terraform/aggrega.modules.tf, und die eigenen Dateien jeder Komponente liegen in dem Verzeichnis, auf das ihr module-Block zeigt: das lokal kopierte RDS-Modul unter modules/db/ und das ECS-Modul des Servers, das neben seinem Recipe im Katalog liegt, unter modules/api/. Die gesamte Root-Konfiguration:
# 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"]}Das Argument environment des Servers trägt die vier Werte, die die Kante angefordert hat. DB_HOST ist ${module.db.db_instance_address}: Das Datenbank-Recipe veröffentlicht eine Referenz auf die eigene Ausgabe db_instance_address des RDS-Moduls über den Modulaufruf, den dieselbe Root als module "db" deklariert, daher wertet Terraform sie hier aus, zur Plan- und Apply-Zeit, und das Modul des Servers erhält die Adresse der Instanz als gewöhnliche Eingabe. Die anderen drei sind reiner Text, den der Compiler im Voraus kannte — der Port, den das Release konfiguriert, und die beiden Namen, die das Aggregate geschrieben hat.
Das funktioniert, weil das Recipe des Servers ein source:-Recipe ist: Sein Mapping wird zu den Argumenten des module-Blocks des Servers, der einzigen Stelle, die Terraform in einem Geltungsbereich auswertet, in dem das Modul des Nachbarn deklariert ist — siehe Den veröffentlichten Wert einer anderen Komponente konsumieren und Ein ausgearbeitetes Paar für die Mechanik und dafür, was schiefgeht, wenn ein Konsument die Referenz irgendwo anders schreibt. Aus demselben Grund planen Sie dieses Verzeichnis — das, das aggrega.modules.tf enthält — statt eines der beiden Modulverzeichnisse für sich.
Auf einer Arbeitskopie dieses Verzeichnisses lädt tofu init -backend=false die Root und die lokal kopierten Module von der Festplatte und ruft nur Provider ab:
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]und tofu validate gibt dann aus:
Success! The configuration is valid.Ein CloudFormation-Stack
aggrega build --release release-one-stack.yaml --auto-pullPull complete: release-one-stack.lock (entities=11, source_artifacts=0, external_inputs=0)Total build time: 6.2sBuild completed: 1 file written to <workspace>/distDer zusammengesetzte Stack landet unter dist/one-stack/cloudformation/cloudformation-stack.json und enthält drei Ressourcen: Db, die RDS-Instanz; Api, den ECS-Service; und ApiTaskDefinition, die Task-Definition, die er ausführt. Die Umgebung des Containers in 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 ist ein Fn::GetAtt auf Endpoint.Address der Instanz, gegen die logische ID Db, die das Datenbank-Recipe aus dem Komponentennamen db ableitet. CloudFormation löst es auf, wenn es den Stack erstellt, und weil die Task-Definition des Servers ein Attribut von Db liest, erstellt es die Instanz zuerst. Siehe Stack-interne Referenzen.
Zwei CloudFormation-Stacks
aggrega build --release release-two-stacks.yaml --auto-pullPull complete: release-two-stacks.lock (entities=11, source_artifacts=0, external_inputs=0)Total build time: 6.2sBuild completed: 2 files written to <workspace>/distIn aggregate.yaml ändert sich nichts. Das Release platziert die Datenbank in der Boundary data und den Server in der Boundary app, sodass jede zu einem eigenen Stack zusammengesetzt wird und die Kante des Servers zur Datenbank von einem Stack in den anderen führt. Der Stack der Datenbank, dist/two-stacks-data/cloudformation/cloudformation-stack.json, veröffentlicht jeden Eintrag, den die Kante konsumiert, als Ausgabe mit einem Export. Seine 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" } } },Auch protocol wird veröffentlicht und trägt keinen Export, weil keine Kante es liest. Der Stack des Servers, dist/two-stacks-app/cloudformation/cloudformation-stack.json, liest jeden der vier unter demselben Namen zurück:
"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"} } ],Jeder Exportname verbindet den Namen des Release, das Ausgabeverzeichnis der erzeugenden Boundary, die Komponente und den Eintrag, daher steht er zur Build-Zeit fest, und der Konsument kann ihn nennen, bevor einer der beiden Stacks existiert. Weder das eine noch das andere Release deklariert hier ein Konto oder eine Region, daher ist das Lesen ein Fn::ImportValue im selben Konto. Wie der Name gebildet wird und wann der Konsument stattdessen kontenübergreifend liest, ist in Stack-übergreifende Verdrahtung dargelegt. Ein Import löst sich nur gegen einen Export auf, der bereits existiert, daher wird der Stack der Datenbank vor dem des Servers erstellt; die beiden Stacks in eine Reihenfolge zu bringen, ist Sache des Operators, außerhalb des Builds.
Das Passwort gehört RDS
Das Aggregate nennt den Benutzer der Datenbank und nichts über ihr Passwort, und kein Release bindet Zugangsdaten an die Datenbank an. Auf beiden Zielen übergibt das vom Manifest ausgewählte Recipe das Passwort an RDS: manage_master_user_password = true am Modulblock oben und ManageMasterUserPassword an der Instanz in jedem Stack. Die Properties der Datenbank in der Ein-Stack-Vorlage:
"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 erzeugt das Administratorpasswort, wenn es die Instanz erstellt, und bewahrt es in AWS Secrets Manager auf. Keine Build-Eingabe trägt ein Passwort, daher schreibt keiner der drei Builds eines in irgendeine Datei. Der Server erhält den Namen des Benutzers und nicht sein Passwort; das Passwort aus Secrets Manager zu lesen, bleibt dem Code überlassen, den das Image des Servers ausführt.
Das Backup ist eine Anbindung
RDS sichert die Instanz selbst und bewahrt jedes automatische Backup 7 Tage lang auf, wenn nichts anderes angegeben ist. Jedes Release bewahrt sie 14 Tage lang auf, indem es core/backup an die Datenbank anbindet, in seinem Eintrag für db:
db: features: backup: type: core/backup infra: retention_days: 14Jedes Manifest bindet das Feature an das FeatureRecipe für sein Ziel, terraform/backup-native oder cloudformation/backup-native, und keines von beiden rendert etwas: Das Backup ist eine Einstellung der Instanz, daher liest das Datenbank-Recipe die Anbindung und schreibt die Aufbewahrung dorthin, wo die Instanz geschrieben wird — backup_retention_period = 14 am Modulblock und "BackupRetentionPeriod": 14 in den Properties der Instanz oben. Deshalb enthält die Ein-Stack-Vorlage genau drei Ressourcen.
Bauen ist nicht Bereitstellen
Jeder Build schreibt Dateien unter dist/ und hält an. Er führt nie Terraform, OpenTofu oder CloudFormation aus, authentifiziert sich nie bei AWS und schlägt keinen der Bezeichner nach, die die Releases nennen. Die Root-Konfiguration zu planen und anzuwenden und die Stacks zu erstellen, sind Schritte, die Sie mit Ihren eigenen Zugangsdaten auf der Ausgabe ausführen, nachdem Sie die Platzhalter ersetzt haben.
Identische Eingabe, identische Ausgabe
Zweimal aus unveränderten Eingaben zu bauen, erzeugt eine byte-identische Ausgabe, für jedes der drei Releases. Der Compiler löst keine Live-Daten auf, daher hat ein erneuter Build nichts zu entdecken, was die Bytes verschieben könnte. Das ist die Eigenschaft, auf die sich ein diff-basiertes Review verlässt.
dist/, .aggrega/ und die *.lock-Dateien werden erzeugt und nicht committet; sie entstehen neu aus den Dateien, die committet sind.