Перейти к содержимому
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 — оба компонента в одной границе, собираемые через сущность 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: database

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

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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 экземпляра, относительно логического ID 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, выходного каталога границы-производителя, компонента и записи, поэтому оно фиксируется во время сборки, и потребитель может назвать его до того, как появится любой из стеков. Ни одна из сущностей 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 генерируются и не коммитятся; они заново создаются из тех файлов, которые коммитятся.