Керована база даних і сервіс, що її читає, на Terraform і CloudFormation
Один Aggregate містить базу даних PostgreSQL і сервер, що її читає. Той самий Aggregate збирається для AWS трьома способами: як одна коренева конфігурація Terraform, де базу даних розгортає опублікований модуль RDS проєкту terraform-aws-modules, а сервер працює як сервіс Amazon ECS на Fargate; як один стек CloudFormation, що містить обидва; і як два стеки CloudFormation — база даних в одному, сервер в іншому.
На кожній цілі сервер отримує адресу бази даних у формі, яку
ця ціль розв’язує сама: посилання на вихідне значення модуля в кореневій конфігурації,
Fn::GetAtt усередині одного стека, Fn::ImportValue між двома. Компілятор
не обчислює жодного з них. Адреса не існує, доки не створено екземпляр,
тож збірка передає посилання далі, а ціль розв’язує його
під час розгортання.
Блоки виводу на цій сторінці скопійовано з реального запуску, згідно з Читання виводу на цих сторінках.
Файли
aggregate.yaml— намір розробника: компонентdbтипуcore/datastore/postgresз логічною базою данихorders, власником якої є рольorders_admin, і компонентapiтипуcore/compute/server, що її використовує. Жоден ключ чи значення в ньому не стосується AWS.manifest-terraform.yaml— прив’язує базу даних до сутності Recipeterraform/postgres-rds-terraform-aws-modules, сервер — доterraform/server-ecs, а сутність Featurecore/backup— доterraform/backup-native.manifest-cloudformation.yaml— прив’язує базу даних доcloudformation/postgres-rds, сервер — доcloudformation/server-ecs, а сутність Featurecore/backup— доcloudformation/backup-native.release-terraform.yaml— обидва компоненти в одній межі, зібрані через Terraform Manifest.release-one-stack.yaml— обидва компоненти в одній межі, зібрані через CloudFormation Manifest, тож обидва збираються в один стек.release-two-stacks.yaml— той самий намір, розділений між двома межами, тож посилання сервера на базу даних перетинає межу стека..aggrega-config.yaml— називає реєстр hub, з якого розв’язується каталог стандартної бібліотеки.
Усі сутності, які використовує цей приклад, містяться в цьому каталозі. Нічого не копіюється поруч із файлами релізу.
Що запитує сервер
Сервер оголошує одне ребро на сокеті, який він називає database, і запитує
чотири із записів, які публікує база даних, під іменами змінних середовища,
які читає його власна конфігурація:
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 не оголошує власного сокета, тому database є
адхок-сокетом: ребро не має ні селектора, ні списку дозволених ін’єкцій, і кожен
ключ from: усе одно має бути одним із тих, що публікує база даних, — див.
adhoc-uses-socket щодо цього контракту. Сутність Aggregate
ніколи не називає ні адреси, ні номера порту, ні хмарного провайдера, і це той самий
файл для всіх трьох збірок нижче.
Що надає оператор
Кожна сутність Release називає в infra.overrides те, що оператор уже запускає
і що читають Recipes: групу підмереж RDS DB і групи безпеки бази даних, а також
кластер ECS, підмережі та групи безпеки, до яких під’єднуються завдання, і роль
виконання, з якою ECS завантажує образ і записує журнали. Образ сервера —
infra.image. Обидві серверні сутності Recipe вимагають образ, кластер,
підмережі, групи безпеки та роль виконання, а Terraform-сутність Recipe бази
даних вимагає групу підмереж: збирання, якому бракує одного з них, зупиняється
і називає ключ, а не обирає мережу чи роль за вас.
Кожне з цих значень — заповнювач: 123456789012 — це номер облікового
запису, який документація AWS використовує в прикладах, а example-cluster,
example-private-db-subnets, ідентифікатори subnet-… і sg-…, роль і
registry.example.com/orders-api:1.0.0 позначають ресурси у вашому власному обліковому записі.
Збирання приймає їх, бо ніколи їх не перевіряє; замініть їх, перш ніж
планувати чи розгортати.
Terraform-сутності Recipes читають свої ключі в написанні terraform з каталогу
(subnet_group, subnet_ids, vpc_security_groups, cluster,
execution_role_arn); CloudFormation-сутності Recipes читають їх під власними
назвами властивостей ресурсів (DBSubnetGroupName, VPCSecurityGroups, Cluster,
Subnets, SecurityGroups, ExecutionRoleArn), тож ті самі значення оператора
пишуться для двох цілей по-різному.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example aws-rds-and-ecs-serviceПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd aws-rds-and-ecs-serviceЗбирання
Цей приклад постачається з трьома релізами, тож укажіть потрібний. За один запуск збирається один реліз. У свіжій копії передайте --auto-pull під час першої збірки кожного релізу, щоб його lock-файл заповнився під час збірки. Перша збірка Terraform отримує модуль RDS із його git-репозиторію на коміті, який фіксує власна прив’язка сутності Recipe:
aggrega build --release release-terraform.yaml --auto-pullВона виводить таке (<workspace> позначає теку цього прикладу):
Pull complete: release-terraform.lock (entities=11, source_artifacts=1, external_inputs=0)Total build time: 9.4sBuild completed: 151 files written to <workspace>/distЩойно lock-файл існує, звичайна команда виконує збірку відповідно до нього:
aggrega build --release release-terraform.yamlTotal build time: 5.7sBuild completed: 151 files written to <workspace>/distЗ ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `aws-rds-and-ecs-service`, викличте один раз інструмент `scaffold`, задавши для `example` значення `aws-rds-and-ecs-service` і не задаючи `dir`: він запише приклад у нову теку `aws-rds-and-ecs-service`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `aws-rds-and-ecs-service`, для `release` — `release-terraform.yaml`, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала збірка; вони лежать у `aws-rds-and-ecs-service/dist/`.Одна коренева конфігурація Terraform
Коренева конфігурація межі створюється в
dist/one-root/terraform/aggrega.modules.tf, а власні файли кожного компонента розміщуються
в каталозі, на який вказує його блок module: вендорований модуль RDS — у
modules/db/, а модуль ECS сервера, що зберігається поруч із його Recipe в
каталозі, — у modules/api/. Уся коренева конфігурація:
# 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"]}Аргумент environment сервера містить чотири значення, які запросила
границя. DB_HOST дорівнює ${module.db.db_instance_address}: Recipe бази даних
публікує посилання на власний вихід db_instance_address модуля RDS
через виклик модуля, який цей самий корінь оголошує як module "db", тож Terraform
обчислює його тут, під час plan і apply, а модуль сервера отримує
адресу інстансу як звичайний вхід. Інші три — звичайний текст, який
компілятор знав заздалегідь: порт, який налаштовує Release, і два імені,
які записав Aggregate.
Це працює, тому що Recipe сервера є Recipe типу source:: його відображення
стає аргументами блоку module сервера, а це єдина позиція, яку
Terraform обчислює в області видимості, де оголошено модуль сусіда, — див.
Використання опублікованого значення іншого компонента
і Робочу пару, щоб дізнатися
механіку, а також що стається, коли споживач записує посилання
будь-де інде. З тієї ж причини виконуйте plan для цього каталогу — того, що містить
aggrega.modules.tf, — а не для окремого каталогу будь-якого з модулів.
На тимчасовій копії цього каталогу tofu init -backend=false завантажує корінь
і вендоровані модулі з диска та отримує лише провайдери:
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]а tofu validate потім виводить:
Success! The configuration is valid.Один стек 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>/distЗібраний стек розміщується у
dist/one-stack/cloudformation/cloudformation-stack.json і містить три
ресурси: Db — екземпляр RDS; Api — сервіс ECS; і
ApiTaskDefinition — визначення завдання, яке він запускає. Середовище контейнера в
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 — це Fn::GetAtt на Endpoint.Address екземпляра, що посилається на
логічний ідентифікатор Db, який Recipe бази даних виводить з імені компонента db.
CloudFormation розв’язує його під час створення стека, і оскільки визначення завдання
сервера читає атрибут Db, спершу створюється екземпляр. Див.
Посилання в межах стека.
Два стеки 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>/distУ aggregate.yaml нічого не змінюється. Сутність Release розміщує базу даних у межі data, а сервер — у межі app, тож кожен збирається у власний стек, і ребро від сервера до бази даних переходить з одного стека в інший. Стек бази даних, dist/two-stacks-data/cloudformation/cloudformation-stack.json, публікує кожен запис, який споживає ребро, як вихідне значення з Export. Його 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 також публікується, але не має Export, бо жодне ребро його не читає. Стек сервера, dist/two-stacks-app/cloudformation/cloudformation-stack.json, зчитує кожне з чотирьох за тим самим ім’ям:
"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"} } ],Кожне ім’я експорту поєднує ім’я релізу, вихідний каталог межі-виробника, компонент і запис, тож воно фіксується під час збирання, і споживач може назвати його ще до того, як з’явиться будь-який зі стеків. Жодна сутність Release тут не оголошує ні облікового запису, ні регіону, тому зчитування — це Fn::ImportValue у межах одного облікового запису. Як будується ім’я і коли споживач натомість зчитує між обліковими записами, описано в розділі Зв’язування між стеками. Імпорт розв’язується лише щодо вже наявного експорту, тому стек бази даних створюється раніше за стек сервера; упорядкування двох стеків — справа оператора, поза збиранням.
Пароль належить самому RDS
Сутність Aggregate називає користувача бази даних і нічого не каже про його пароль, і жодна
сутність Release не прикріплює до бази даних облікові дані. На обох цілях Recipe, який вибирає
Manifest, передає пароль RDS: manage_master_user_password = true
у блоці модуля вище та ManageMasterUserPassword в екземплярі в
кожному стеку. Properties бази даних у шаблоні з одним стеком:
"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 генерує пароль адміністратора під час створення екземпляра і зберігає його в AWS Secrets Manager. Жодні вхідні дані збірки не містять пароля, тож жодна з трьох збірок не записує його в жоден файл. Сервер отримує ім’я користувача, але не його пароль; читання пароля із Secrets Manager покладено на код, який виконує образ сервера.
Резервне копіювання — це підключення
RDS сама створює резервні копії екземпляра і, якщо не вказано інше, зберігає кожну автоматичну резервну копію 7 днів. Кожна сутність Release зберігає їх 14 днів, підключаючи core/backup до бази даних у своєму записі для db:
db: features: backup: type: core/backup infra: retention_days: 14Кожна сутність Manifest прив’язує Feature до сутності FeatureRecipe для своєї цілі, terraform/backup-native або cloudformation/backup-native, і жодна з них нічого не рендерить: резервне копіювання — це налаштування екземпляра, тож сутність Recipe бази даних читає підключення і записує строк зберігання туди, де записується екземпляр, — backup_retention_period = 14 у блоці модуля та "BackupRetentionPeriod": 14 у Properties екземпляра вище. Саме тому шаблон з одним стеком містить рівно три ресурси.
Збирання — це не розгортання
Кожне збирання записує файли в dist/ і зупиняється. Воно ніколи не запускає Terraform,
OpenTofu чи CloudFormation, ніколи не автентифікується в AWS і не шукає жодного
з ідентифікаторів, які називають сутності Releases. Планування й застосування кореневої
конфігурації, а також створення стеків — це кроки, які ви виконуєте з результатом, зі
своїми власними обліковими даними, після заміни заповнювачів.
Ідентичні вхідні дані — ідентичний результат
Дві збірки з незмінних вхідних даних дають побайтово ідентичний результат для кожного з трьох релізів. Компілятор не звертається до жодних живих даних, тож повторній збірці нічого виявляти, що могло б змінити байти. Саме на цю властивість спирається перевірка на основі порівняння відмінностей (diff).
dist/, .aggrega/ і файли *.lock генеруються й не комітяться;
вони відтворюються з тих файлів, які комітяться.