Zarządzana baza danych i usługa, która z niej czyta, w Terraform i CloudFormation
Jeden Aggregate zawiera bazę danych PostgreSQL i serwer, który z niej czyta. Ten sam Aggregate jest budowany na trzy sposoby dla AWS: jako jedna główna konfiguracja Terraform, w której bazę danych udostępnia opublikowany moduł RDS projektu terraform-aws-modules, a serwer działa jako usługa Amazon ECS na Fargate; jako jeden stos CloudFormation zawierający oba elementy; oraz jako dwa stosy CloudFormation, z bazą danych w jednym i serwerem w drugim.
Na każdym celu serwer otrzymuje adres bazy danych w postaci, którą
ten cel sam rozwiązuje: odwołania do wyjścia modułu w konfiguracji głównej,
Fn::GetAtt wewnątrz jednego stosu, Fn::ImportValue między dwoma. Kompilator
nie oblicza żadnego z nich. Adres nie istnieje, dopóki instancja
nie zostanie utworzona, więc proces budowania przekazuje dalej odwołanie, a cel rozwiązuje je
podczas wdrażania.
Bloki wyjścia na tej stronie są skopiowane z rzeczywistego uruchomienia, zgodnie z Odczytywanie wyjścia na tych stronach.
Pliki
aggregate.yaml— intencja programisty: komponentdbtypucore/datastore/postgresz logiczną bazą danychorders, której właścicielem jest rolaorders_admin, oraz komponentapitypucore/compute/server, który z niej korzysta. Żaden klucz ani żadna wartość w tym pliku nie dotyczy AWS.manifest-terraform.yaml— wiąże bazę danych z encją Recipeterraform/postgres-rds-terraform-aws-modules, serwer zterraform/server-ecs, a encję Featurecore/backupzterraform/backup-native.manifest-cloudformation.yaml— wiąże bazę danych zcloudformation/postgres-rds, serwer zcloudformation/server-ecs, a encję Featurecore/backupzcloudformation/backup-native.release-terraform.yaml— oba komponenty w jednej granicy, budowane przez encję Manifest dla Terraform.release-one-stack.yaml— oba komponenty w jednej granicy, budowane przez encję Manifest dla CloudFormation, dzięki czemu oba składają się w jeden stos.release-two-stacks.yaml— ta sama intencja podzielona na dwie granice, dzięki czemu odwołanie serwera do bazy danych przekracza krawędź stosu..aggrega-config.yaml— wskazuje rejestr hub, z którego rozwiązywany jest katalog biblioteki standardowej.
Wszystkie encje używane w tym przykładzie znajdują się w tym katalogu. Nic nie jest kopiowane obok plików wydania.
Czego żąda serwer
Serwer deklaruje jedną krawędź, na gnieździe, które nazywa database, i żąda
czterech wpisów publikowanych przez bazę danych, pod nazwami zmiennych
środowiskowych, które odczytuje jego własna konfiguracja:
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 nie deklaruje własnego gniazda, więc database jest
gniazdem ad hoc: krawędź nie ma selektora ani listy dozwolonych wstrzyknięć, a każdy
klucz from: nadal musi być kluczem publikowanym przez bazę danych — ten kontrakt opisuje
adhoc-uses-socket. Encja Aggregate
nigdy nie podaje adresu, numeru portu ani dostawcy chmury i jest tym samym
plikiem dla wszystkich trzech poniższych kompilacji.
Co dostarcza operator
Każda encja Release wymienia w infra.overrides zasoby, które operator już utrzymuje, a encje Recipes odczytują: grupę podsieci RDS DB i grupy zabezpieczeń bazy danych, a także klaster ECS, podsieci i grupy zabezpieczeń, do których dołączane są zadania, oraz rolę wykonawczą, za pomocą której ECS pobiera obraz i zapisuje logi. Obraz serwera to infra.image. Obie encje Recipes serwera wymagają obrazu, klastra, podsieci, grup zabezpieczeń i roli wykonawczej, a encja Recipe bazy danych dla Terraform wymaga grupy podsieci: kompilacja, w której brakuje którejś z tych wartości, zatrzymuje się i wskazuje klucz, zamiast samodzielnie wybierać sieć lub rolę.
Każda z tych wartości jest symbolem zastępczym — 123456789012 to numer konta, którego dokumentacja AWS używa w przykładach, a example-cluster, example-private-db-subnets, identyfikatory subnet-… i sg-…, rola oraz registry.example.com/orders-api:1.0.0 oznaczają zasoby na własnym koncie.
Kompilacja je akceptuje, ponieważ nigdy ich nie sprawdza; należy je zastąpić przed wykonaniem planu lub wdrożenia.
Encje Recipes dla Terraform odczytują swoje klucze w pisowni terraform stosowanej w katalogu
(subnet_group, subnet_ids, vpc_security_groups, cluster,
execution_role_arn); encje Recipes dla CloudFormation odczytują je pod nazwami właściwości samych zasobów (DBSubnetGroupName, VPCSecurityGroups, Cluster,
Subnets, SecurityGroups, ExecutionRoleArn), więc te same wartości operatora są zapisywane inaczej w obu środowiskach docelowych.
Generowanie przykładu
Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example aws-rds-and-ecs-serviceNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd aws-rds-and-ecs-serviceKompilacja
Ten przykład zawiera trzy wydania, dlatego należy wskazać to, które ma zostać zbudowane. W jednym uruchomieniu budowane jest jedno wydanie. W świeżej kopii przy pierwszym budowaniu każdego wydania należy przekazać --auto-pull, aby jego plik blokady został wypełniony podczas budowania. Pierwsze budowanie dla Terraform pobiera moduł RDS z jego repozytorium git, w commicie zapisanym we własnym przypięciu encji Recipe:
aggrega build --release release-terraform.yaml --auto-pullPolecenie wypisuje, gdzie <workspace> oznacza katalog tego przykładu:
Pull complete: release-terraform.lock (entities=11, source_artifacts=1, external_inputs=0)Total build time: 9.4sBuild completed: 151 files written to <workspace>/distGdy plik blokady już istnieje, zwykłe polecenie buduje na jego podstawie:
aggrega build --release release-terraform.yamlTotal build time: 5.7sBuild completed: 151 files written to <workspace>/distZ asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder obszaru roboczego nie zawiera jeszcze folderu `aws-rds-and-ecs-service`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `aws-rds-and-ecs-service` i bez `dir`: zapisze ono przykład w nowym folderze `aws-rds-and-ecs-service`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `aws-rds-and-ecs-service`, `release` ustawionym na `release-terraform.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true. Powiedz mi, które pliki zapisało budowanie; znajdują się w `aws-rds-and-ecs-service/dist/`.Jedna konfiguracja główna Terraform
Konfiguracja główna granicy trafia do
dist/one-root/terraform/aggrega.modules.tf, a własne pliki każdego komponentu znajdują się
w katalogu, na który wskazuje jego blok module: dołączony moduł RDS w
modules/db/, a moduł ECS serwera, przechowywany w katalogu obok jego encji Recipe,
w modules/api/. Cała konfiguracja główna:
# 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"]}Argument environment serwera przenosi cztery wartości, o które poprosiła krawędź. DB_HOST to ${module.db.db_instance_address}: encja Recipe bazy danych
publikuje odwołanie do własnego wyjścia db_instance_address modułu RDS
przez wywołanie modułu, które ta sama konfiguracja główna deklaruje jako module "db", więc Terraform
wartościuje je tutaj, w czasie plan i apply, a moduł serwera otrzymuje
adres instancji jako zwykłe wejście. Pozostałe trzy to zwykły tekst, który
kompilator znał z góry — port konfigurowany przez encję Release i dwie nazwy
zapisane w encji Aggregate.
Działa to, ponieważ encja Recipe serwera jest encją Recipe typu source:: jej mapowanie
staje się argumentami bloku module serwera, czyli jedynego miejsca,
które Terraform wartościuje w zakresie, w którym zadeklarowany jest moduł sąsiada — mechanizm
oraz to, co idzie nie tak, gdy konsument zapisze odwołanie gdziekolwiek indziej, opisują
Korzystanie z wartości opublikowanej przez inny komponent
i Przykładowa para. Z tego samego powodu należy planować ten katalog — ten, który zawiera
aggrega.modules.tf — a nie którykolwiek z katalogów modułów osobno.
Na roboczej kopii tego katalogu tofu init -backend=false wczytuje z dysku konfigurację główną
i dołączone moduły, a pobiera jedynie dostawców:
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]a następnie tofu validate wypisuje:
Success! The configuration is valid.Jeden stos CloudFormation
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>/distZłożony stos trafia do
dist/one-stack/cloudformation/cloudformation-stack.json i zawiera trzy
zasoby: Db, instancję RDS; Api, usługę ECS; oraz
ApiTaskDefinition, definicję zadania, którą ta usługa uruchamia. Środowisko kontenera w
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 to Fn::GetAtt na atrybucie Endpoint.Address instancji, odnoszący się do
identyfikatora logicznego Db, który Recipe bazy danych wyprowadza z nazwy komponentu db.
CloudFormation rozwiązuje go podczas tworzenia stosu, a ponieważ definicja zadania
serwera odczytuje atrybut Db, najpierw tworzy instancję. Zob.
Odwołania wewnątrz stosu.
Dwa stosy CloudFormation
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>/distW aggregate.yaml nic się nie zmienia. Encja Release umieszcza bazę danych w granicy
data, a serwer w granicy app, więc każde z nich jest składane w
osobny stos, a krawędź serwera do bazy danych przechodzi z jednego stosu
do drugiego. Stos bazy danych,
dist/two-stacks-data/cloudformation/cloudformation-stack.json,
publikuje każdy wpis konsumowany przez krawędź jako wyjście z Export. Jego
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 także jest publikowany i nie ma Export, ponieważ żadna krawędź go nie odczytuje.
Stos serwera, dist/two-stacks-app/cloudformation/cloudformation-stack.json,
odczytuje każdy z czterech wpisów z powrotem pod tą samą nazwą:
"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"} } ],Każda nazwa eksportu łączy nazwę encji Release, katalog wyjściowy granicy producenta,
komponent i wpis, więc jest ustalona w czasie budowania, a
konsument może ją wskazać, zanim powstanie którykolwiek ze stosów. Żadna z encji Release nie deklaruje tu
konta ani regionu, więc odczyt to Fn::ImportValue w obrębie tego samego konta. Sposób
budowania nazwy oraz to, kiedy konsument odczytuje wartości między kontami, opisano
w sekcji Połączenia między stosami.
Import rozwiązuje się tylko względem eksportu, który już istnieje, więc
stos bazy danych jest tworzony przed stosem serwera; kolejność tworzenia obu stosów
należy do operatora i leży poza budowaniem.
Hasło należy do RDS
Encja Aggregate określa użytkownika bazy danych, ale nic nie mówi o jego haśle, a żadna encja
Release nie dołącza do bazy danych poświadczeń. Na obu platformach docelowych encja Recipe wybrana przez encję
Manifest przekazuje hasło do RDS: manage_master_user_password = true
w powyższym bloku modułu oraz ManageMasterUserPassword w instancji w
każdym stosie. Sekcja Properties bazy danych w szablonie z jednym stosem:
"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 generuje hasło administratora podczas tworzenia instancji i przechowuje je w AWS Secrets Manager. Żadne wejście kompilacji nie zawiera hasła, więc żadna z trzech kompilacji nie zapisuje go w żadnym pliku. Serwer otrzymuje nazwę użytkownika, ale nie jego hasło; odczytanie hasła z Secrets Manager pozostawiono kodowi uruchamianemu przez obraz serwera.
Kopia zapasowa jest dołączeniem
RDS sam tworzy kopie zapasowe instancji i, jeśli nic nie wskazuje inaczej, przechowuje każdą automatyczną kopię przez 7 dni. Każda encja Release przechowuje je przez 14 dni, dołączając core/backup do bazy danych we wpisie dla db:
db: features: backup: type: core/backup infra: retention_days: 14Każdy Manifest wiąże encję Feature z encją FeatureRecipe dla swojego celu, terraform/backup-native lub cloudformation/backup-native, i żadna z nich niczego nie renderuje: kopia zapasowa jest ustawieniem instancji, więc encja Recipe bazy danych odczytuje dołączenie i zapisuje okres przechowywania tam, gdzie zapisywana jest instancja — backup_retention_period = 14 w bloku modułu oraz "BackupRetentionPeriod": 14 we właściwościach Properties instancji powyżej. Dlatego szablon jednego stosu zawiera dokładnie trzy zasoby.
Budowanie to nie wdrażanie
Każde budowanie zapisuje pliki w dist/ i się kończy. Nigdy nie uruchamia Terraform,
OpenTofu ani CloudFormation, nigdy nie uwierzytelnia się w AWS i nie sprawdza żadnego
z identyfikatorów, które podają encje Releases. Planowanie i stosowanie konfiguracji
root oraz tworzenie stosów to kroki wykonywane na wyniku, z
własnymi poświadczeniami, po zastąpieniu symboli zastępczych.
Identyczne wejście, identyczne wyjście
Dwukrotne budowanie z niezmienionych danych wejściowych daje wynik identyczny co do bajtu dla każdego z trzech wydań. Kompilator nie rozwiązuje żadnych danych na żywo, więc ponowne budowanie nie ma niczego do odkrycia, co mogłoby zmienić bajty. Na tej właściwości opiera się przegląd oparty na różnicach.
dist/, .aggrega/ i pliki *.lock są generowane i nie są zatwierdzane w repozytorium;
odtwarza się je z plików, które są w nim zatwierdzone.