Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

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: komponent db typu core/datastore/postgres z logiczną bazą danych orders, której właścicielem jest rola orders_admin, oraz komponent api typu core/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ą Recipe terraform/postgres-rds-terraform-aws-modules, serwer z terraform/server-ecs, a encję Feature core/backup z terraform/backup-native.
  • manifest-cloudformation.yaml — wiąże bazę danych z cloudformation/postgres-rds, serwer z cloudformation/server-ecs, a encję Feature core/backup z cloudformation/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: database

core/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:

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

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:

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

Kompilacja

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:

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

Polecenie 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.4s
Build completed: 151 files written to <workspace>/dist

Gdy plik blokady już istnieje, zwykłe polecenie buduje na jego podstawie:

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

Z 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

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

Zł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

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

W 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: 14

Każ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.