Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Un database gestito e il servizio che lo legge, su Terraform e CloudFormation

Un Aggregate contiene un database PostgreSQL e il server che lo legge. Lo stesso Aggregate viene costruito in tre modi per AWS: come un’unica configurazione radice Terraform, con il database fornito dal modulo RDS pubblicato dal progetto terraform-aws-modules e il server eseguito come servizio Amazon ECS su Fargate; come un unico stack CloudFormation che li contiene entrambi; e come due stack CloudFormation, il database in uno e il server nell’altro.

Su ciascuna destinazione il server riceve l’indirizzo del database nella forma che quella destinazione risolve da sé: un riferimento a un output di modulo nella configurazione radice, un Fn::GetAtt all’interno di un unico stack, un Fn::ImportValue tra due. Il compilatore non ne valuta nessuno. L’indirizzo non esiste finché l’istanza non viene creata, quindi il build convoglia un riferimento senza risolverlo e la destinazione lo risolve quando esegue la distribuzione.

I blocchi di output in questa pagina sono copiati da un’esecuzione reale, secondo Leggere l’output in queste pagine.

File

  • aggregate.yaml — intento dello sviluppatore: un componente db di tipo core/datastore/postgres con un database logico orders di proprietà del ruolo orders_admin, e un componente api di tipo core/compute/server che lo usa. Nessuna chiave o valore al suo interno riguarda AWS.
  • manifest-terraform.yaml — vincola il database alla Recipe terraform/postgres-rds-terraform-aws-modules, il server a terraform/server-ecs e la Feature core/backup a terraform/backup-native.
  • manifest-cloudformation.yaml — vincola il database a cloudformation/postgres-rds, il server a cloudformation/server-ecs e la Feature core/backup a cloudformation/backup-native.
  • release-terraform.yaml — entrambi i componenti in un unico confine, costruiti tramite il Manifest Terraform.
  • release-one-stack.yaml — entrambi i componenti in un unico confine, costruiti tramite il Manifest CloudFormation, così entrambi si assemblano in un unico stack.
  • release-two-stacks.yaml — lo stesso intento suddiviso su due confini, così il riferimento del server al database attraversa il bordo di uno stack.
  • .aggrega-config.yaml — nomina il registry dell’hub da cui si risolve il catalogo della libreria standard.

Le entità usate da questo esempio risiedono tutte in quel catalogo. Nulla viene copiato accanto ai file di release.

Che cosa chiede il server

Il server dichiara un arco, su un socket che chiama database, e chiede quattro delle voci che il database pubblica, con i nomi di variabile d’ambiente che la sua configurazione legge:

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 non dichiara alcun socket proprio, quindi database è un socket ad hoc: l’arco non porta alcun selettore né alcuna allowlist di inject, e ogni chiave from: deve comunque essere una che il database pubblica — vedi adhoc-uses-socket per quel contratto. L’Aggregate non nomina mai un indirizzo, un numero di porta o un provider cloud, ed è lo stesso file per tutti e tre i build più sotto.

Che cosa fornisce l’operatore

Ogni Release nomina, sotto infra.overrides, elementi che l’operatore gestisce già e che le Recipes leggono: il DB subnet group di RDS e i security group del database, e il cluster ECS, le subnet e i security group a cui si collegano i task, e il ruolo di esecuzione con cui ECS scarica l’immagine e scrive i log. L’immagine del server è infra.image. Entrambe le Recipes del server richiedono l’immagine, il cluster, le subnet, i security group e il ruolo di esecuzione, e la Recipe Terraform del database richiede il subnet group: un build a cui ne manca uno si arresta, nominando la chiave, anziché scegliere una rete o un ruolo al posto tuo.

Ognuno di quei valori è un segnaposto — 123456789012 è il numero di account che la documentazione AWS usa negli esempi, e example-cluster, example-private-db-subnets, gli ID subnet-… e sg-…, il ruolo e registry.example.com/orders-api:1.0.0 rappresentano risorse del tuo account. Il build li accetta perché non li verifica mai; sostituiscili prima di eseguire il plan o la distribuzione.

Le Recipes Terraform leggono le loro chiavi nella grafia terraform del catalogo (subnet_group, subnet_ids, vpc_security_groups, cluster, execution_role_arn); le Recipes CloudFormation le leggono con i nomi propri delle proprietà delle risorse (DBSubnetGroupName, VPCSecurityGroups, Cluster, Subnets, SecurityGroups, ExecutionRoleArn), quindi gli stessi valori dell’operatore si scrivono in modo diverso sulle due destinazioni.

Generare l’esempio

Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

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

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

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

Build

Questo esempio include tre release, quindi nomina quella che vuoi. Per ogni esecuzione viene eseguito il build di una sola release. In una copia appena creata, passa --auto-pull la prima volta che viene eseguito il build di ciascuna release, così il suo lockfile viene riempito durante il build. Il primo build Terraform scarica il modulo RDS dal suo repository git, al commit registrato dal fissaggio proprio della Recipe:

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

Stampa, con <workspace> al posto della cartella di questo esempio:

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

Una volta che il lockfile esiste, il comando semplice esegue il build in base a esso:

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

Con un assistente AI

Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.

Usa solo gli strumenti di Aggrega e non creare tu stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `aws-rds-and-ecs-service`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `aws-rds-and-ecs-service` e senza `dir`: scrive l’esempio in una nuova cartella `aws-rds-and-ecs-service`. Poi chiama lo strumento `build` con `workspace_root` impostato su `aws-rds-and-ecs-service`, `release` impostato su `release-terraform.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `aws-rds-and-ecs-service/dist/`.

Un’unica configurazione radice Terraform

La configurazione radice del confine finisce in dist/one-root/terraform/aggrega.modules.tf, e i file propri di ciascun componente si trovano nella directory a cui punta il suo blocco module: il modulo RDS copiato localmente sotto modules/db/, e il modulo ECS del server, tenuto accanto alla sua Recipe nel catalogo, sotto modules/api/. L’intera configurazione radice:

# 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’argomento environment del server porta i quattro valori che l’arco ha richiesto. DB_HOST è ${module.db.db_instance_address}: la Recipe del database pubblica un riferimento all’output db_instance_address proprio del modulo RDS tramite la chiamata di modulo che questa stessa radice dichiara come module "db", quindi Terraform lo valuta qui, al momento del plan e dell’apply, e il modulo del server riceve l’indirizzo dell’istanza come un normale input. Gli altri tre sono testo semplice che il compilatore conosceva in anticipo — la porta che la Release configura e i due nomi che l’Aggregate ha scritto.

Questo funziona perché la Recipe del server è una Recipe source:: la sua mappatura diventa gli argomenti del blocco module del server, che è l’unica posizione che Terraform valuta in un ambito in cui è dichiarato il modulo vicino — vedi Consumare il valore pubblicato da un altro componente e Una coppia svolta per i meccanismi, e per ciò che va storto quando un consumatore scrive il riferimento altrove. Per lo stesso motivo, esegui il plan di questa directory — quella che contiene aggrega.modules.tf — anziché di una delle due directory dei moduli da sola.

Su una copia di prova di quella directory, tofu init -backend=false carica dal disco la radice e i moduli copiati localmente e scarica solo i provider:

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]

e tofu validate stampa quindi:

Success! The configuration is valid.

Un unico 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

Lo stack assemblato finisce in dist/one-stack/cloudformation/cloudformation-stack.json, e contiene tre risorse: Db, l’istanza RDS; Api, il servizio ECS; e ApiTaskDefinition, la task definition che esegue. L’ambiente del container 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 è un Fn::GetAtt sull’Endpoint.Address dell’istanza, rispetto all’ID logico Db che la Recipe del database deriva dal nome di componente db. CloudFormation lo risolve quando crea lo stack e, poiché la task definition del server legge un attributo di Db, crea prima l’istanza. Vedi Riferimenti all’interno dello stack.

Due stack 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

Nulla cambia in aggregate.yaml. La Release colloca il database nel confine data e il server nel confine app, così ciascuno si assembla in uno stack proprio, e l’arco del server verso il database passa da uno stack all’altro. Lo stack del database, dist/two-stacks-data/cloudformation/cloudformation-stack.json, pubblica ogni voce che l’arco consuma come output con un Export. I suoi 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"
}
}
},

Anche protocol viene pubblicato, e non porta alcun Export perché nessun arco lo legge. Lo stack del server, dist/two-stacks-app/cloudformation/cloudformation-stack.json, rilegge ciascuna delle quattro voci con lo stesso nome:

"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"}
}
],

Ogni nome di export unisce il nome della Release, la directory di output del confine produttore, il componente e la voce, quindi è fissato al momento del build e il consumatore può nominarlo prima che uno qualsiasi dei due stack esista. Nessuna Release qui dichiara un account o una regione, quindi la lettura è un Fn::ImportValue nello stesso account. Come viene costruito il nome, e quando invece il consumatore legge tra account diversi, è spiegato in Cablaggio tra stack. Un import si risolve solo rispetto a un export che esiste già, quindi lo stack del database viene creato prima di quello del server; ordinare i due stack spetta all’operatore, al di fuori del build.

La password è quella di RDS

L’Aggregate nomina l’utente del database e nulla sulla sua password, e nessuna Release associa una credenziale al database. Su entrambe le destinazioni la Recipe selezionata dal Manifest affida la password a RDS: manage_master_user_password = true sul blocco del modulo sopra, e ManageMasterUserPassword sull’istanza in ciascuno stack. Le Properties del database nel template a stack singolo:

"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 genera la password dell’amministratore quando crea l’istanza e la conserva in AWS Secrets Manager. Nessun input del build porta una password, quindi nessuno dei tre build ne scrive una in alcun file. Il server riceve il nome dell’utente e non la sua password; leggere la password da Secrets Manager è lasciato al codice che l’immagine del server esegue.

Il backup è un’associazione

RDS esegue da sé il backup dell’istanza e conserva ogni backup automatico per 7 giorni quando nulla indica altrimenti. Ogni Release li conserva per 14 associando core/backup al database, nella sua voce per db:

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

Ogni Manifest vincola la Feature alla FeatureRecipe per la sua destinazione, terraform/backup-native o cloudformation/backup-native, e nessuna delle due renderizza nulla: il backup è un’impostazione dell’istanza, quindi la Recipe del database legge l’associazione e scrive la conservazione dove viene scritta l’istanza — backup_retention_period = 14 sul blocco del modulo, e "BackupRetentionPeriod": 14 nelle Properties dell’istanza sopra. Ecco perché il template a stack singolo contiene esattamente tre risorse.

Eseguire il build non è distribuire

Ogni build scrive file sotto dist/ e si ferma. Non esegue mai Terraform, OpenTofu o CloudFormation, non si autentica mai presso AWS e non verifica nessuno degli identificatori che le Releases nominano. Eseguire il plan e l’apply della configurazione radice, e creare gli stack, sono passi che compi sull’output, con le tue credenziali, dopo aver sostituito i segnaposto.

Input identico, output identico

Eseguire due volte il build da input invariati produce un output identico byte per byte, per ciascuna delle tre release. Il compilatore non risolve alcun dato live, quindi una ricompilazione non ha nulla da scoprire che possa spostare i byte. È la proprietà su cui si basa una revisione basata sui diff.

dist/, .aggrega/ e i file *.lock sono generati e non vengono sottoposti a commit; si rigenerano dai file che lo sono.