Управляемая база данных и читающий её сервис на 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— оба компонента в одной границе, собираемые через сущность Manifest для Terraform.release-one-stack.yaml— оба компонента в одной границе, собираемые через сущность Manifest для CloudFormation, поэтому оба собираются в один стек.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 —
сокет ad-hoc: ребро не несёт ни селектора, ни списка разрешённых для внедрения значений, и каждый
ключ from: всё равно должен быть одним из тех, что публикует база данных, — этот контракт описан в
adhoc-uses-socket. Aggregate
никогда не называет ни адреса, ни номера порта, ни облачного провайдера и остаётся одним и тем же
файлом для всех трёх сборок ниже.
Что предоставляет оператор
Каждая сущность Release указывает в infra.overrides то, что оператор уже эксплуатирует и что читают Recipes: группу подсетей RDS DB и группы безопасности базы данных, а также кластер ECS, подсети и группы безопасности, к которым подключаются задачи, и роль выполнения, с которой ECS загружает образ и записывает журналы. Образ сервера задаётся в infra.image. Обе сущности Recipes сервера требуют образ, кластер, подсети, группы безопасности и роль выполнения, а Recipe базы данных для Terraform требует группу подсетей: сборка, в которой чего-то из этого нет, останавливается и называет ключ, а не выбирает сеть или роль за вас.
Каждое из этих значений — заполнитель: 123456789012 — номер учётной записи, который документация AWS использует в примерах, а example-cluster,
example-private-db-subnets, идентификаторы subnet-… и sg-…, роль и
registry.example.com/orders-api:1.0.0 обозначают ресурсы в вашей собственной учётной записи.
Сборка принимает их, потому что никогда их не проверяет; замените их, прежде чем выполнять планирование или развёртывание.
Recipes для Terraform читают свои ключи в написании terraform, принятом в каталоге
(subnet_group, subnet_ids, vpc_security_groups, cluster,
execution_role_arn); Recipes для CloudFormation читают их под собственными именами свойств ресурсов (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 экземпляра, относительно
логического ID 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, выходного каталога
границы-производителя, компонента и записи, поэтому оно фиксируется во время сборки,
и потребитель может назвать его до того, как появится любой из стеков. Ни одна из
сущностей 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 генерируются и не коммитятся;
они заново создаются из тех файлов, которые коммитятся.