Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Керована база даних і сервіс, що її читає, на 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 — прив’язує базу даних до сутності Recipe terraform/postgres-rds-terraform-aws-modules, сервер — до terraform/server-ecs, а сутність Feature core/backup — до terraform/backup-native.
  • manifest-cloudformation.yaml — прив’язує базу даних до cloudformation/postgres-rds, сервер — до cloudformation/server-ecs, а сутність Feature core/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: database

core/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), тож ті самі значення оператора пишуться для двох цілей по-різному.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

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

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

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

Збирання

Цей приклад постачається з трьома релізами, тож укажіть потрібний. За один запуск збирається один реліз. У свіжій копії передайте --auto-pull під час першої збірки кожного релізу, щоб його lock-файл заповнився під час збірки. Перша збірка Terraform отримує модуль RDS із його git-репозиторію на коміті, який фіксує власна прив’язка сутності Recipe:

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

Щойно lock-файл існує, звичайна команда виконує збірку відповідно до нього:

Terminal window
aggrega build --release release-terraform.yaml
Total build time: 5.7s
Build 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

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

Зібраний стек розміщується у 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

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

У 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 генеруються й не комітяться; вони відтворюються з тих файлів, які комітяться.