Стек CloudFormation с вложениями
Управляемая база данных и приложение, которое её читает, описанные один раз как намерение разработчика и собранные в шаблоны стеков AWS CloudFormation. Два вложения приносят собственные ресурсы — сигнал тревоги на базе данных и параметр общих настроек на границе, — поэтому этот пример показывает, куда ресурсы вложения попадают в собранном стеке и как они именуются рядом с ресурсами компонента.
Одно и то же намерение разработчика собирается тремя способами: как один стек, как два стека со ссылкой, пересекающей границу между ними, и — намеренно — как сборка, которая останавливается.
Блоки вывода на этой странице скопированы из реального запуска, согласно разделу Чтение вывода на этих страницах.
Файлы
aggregate.yaml— намерение разработчика: база данныхpayments-dbтипаcore/datastore/mariadbиreporting-appтипаexample/compute/db-reader, которое объявляет, что использует эту базу данных. Ничего об AWS здесь нет. Блокfeatures:базы данных содержитstorage-headroom, присоединяющийexample/storage-alarm.release-one-stack.yaml— оба компонента в одной границе, поэтому оба собираются в единый стек. Присоединяетcore/shared-configко всей границе.release-two-stacks.yaml— то же намерение, разделённое на две границы, поэтому ссылка приложения на базу данных пересекает границу стека.release-negative-name-collision.yamlсaggregate-name-collision.yaml— сборка должна завершиться ошибкой. Присоединяет оповещение к одному компоненту дважды.manifest.yaml— связывает каждый тип компонента и каждую присоединённую сущность Feature с сущностью Recipe, которая реализует её на этой целевой платформе..aggrega-config.yaml— указывает реестр хаба, из которого разрешаются сущности каталога.
Каждый релиз связывает слот root_password базы данных в своей записи для payments-db с core/generated-secret. На этой целевой платформе паролем администратора владеет RDS, и сущность Recipe базы данных, которую выбирает Manifest, содержит директиву, указывающую на это; поэтому связывание — решение оператора, записанное в Release, а Aggregate ничего о нём не говорит.
Каждый релиз также подключает core/backup к payments-db с infra.retention_days: 14, а Manifest привязывает его к cloudformation/backup-native. Если не указано иное, RDS хранит автоматические резервные копии экземпляра 7 дней; это вложение хранит каждую 14 дней. FeatureRecipe ничего не отрисовывает: резервное копирование — это настройка экземпляра, поэтому сущность Recipe базы данных читает вложение и записывает "BackupRetentionPeriod": 14 в собственные Properties экземпляра.
Все сущности, которые использует этот пример, находятся в опубликованном каталоге. Ничего не копируется рядом с файлами релизов, поэтому пример разрешается относительно каталога в его текущем состоянии, а не относительно его частного снимка.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example cloudformation-rds-stackЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd cloudformation-rds-stackСборка
В этом примере три релиза, поэтому укажите нужный. За один запуск собирается один релиз. Первой сборке каждого релиза нужен его lock-файл, который записывает pull:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yamlСборка выводит следующее (<workspace> обозначает папку этого примера):
Total build time: 4.1sBuild completed: 1 file written to <workspace>/distСобранный стек помещается в
dist/one-stack/cloudformation/cloudformation-stack.json. Каждый компонент и
каждое присоединение, которые рендерятся в этот каталог, вносят вклад в этот единственный шаблон —
провайдер выдаёт один стек на чистом JSON, а не отдельный файл для каждого участника.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочего пространства ещё нет папки `cloudformation-rds-stack`, вызовите один раз инструмент `scaffold` с `example`, равным `cloudformation-rds-stack`, и без `dir`: он запишет пример в новую папку `cloudformation-rds-stack`. Затем вызовите инструмент `build` с `workspace_root`, равным `cloudformation-rds-stack`, `release`, равным `release-one-stack.yaml`, `auto_pull`, равным true, и `write`, равным true. Сообщите, какие файлы записала сборка; они находятся в `cloudformation-rds-stack/dist/`.Что попадает в результат и кто это внёс
Сборка с одним стеком собирает четыре ресурса от четырёх разных источников:
| Ресурс | Источник |
|---|---|
PaymentsDb | собственный Recipe компонента базы данных |
PaymentsDbStorageHeadroom | подключение storage-headroom к этому компоненту |
AppSharedConfig | подключение shared-settings к границе |
ReportingApp | собственный Recipe компонента приложения |
Вложения backup на payments-db нет в таблице, потому что оно не вносит собственного ресурса: то, что оно задаёт, попадает внутрь PaymentsDb.
Каждый ресурс содержит блок происхождения, указывающий источник, от которого он получен, поэтому обе части остаются различимыми внутри стека, в который внесли вклад обе:
"PaymentsDbStorageHeadroom": { "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/aggregate-name": "aggregate", "aggrega.ai/boundary-path": "app", [… omitted: a compiler-version entry, which moves with the build] "aggrega.ai/component-id": "cfr--payments-db--storage-headroom", "aggrega.ai/environment": "production", "aggrega.ai/provider": "cloudformation", [… omitted: a provider-version entry, which moves with the build] "aggrega.ai/recipe-uri": "storage-alarm:1.0.0" } }, [… omitted: the alarm's Properties, printed in full just below] "Type": "AWS::CloudWatch::Alarm" },Две записи о версиях — единственные строки этого блока, которые меняются между
сборками, поэтому они опущены; третий пропуск — это лишь Properties сигнала тревоги,
выведенные отдельно ниже. Всё показанное — это то, что запишет ваша собственная
сборка.
Сигнал тревоги — ресурс подключения, а не базы данных. Отключение
storage-headroom от сущности Aggregate удаляет ровно этот ресурс и единственный
публикуемый им вывод, а PaymentsDb остаётся побайтово таким же, как был.
Имя ресурса подключения содержит область, к которой относится подключение
Feature создаётся один раз и подключается многократно, поэтому имя, которое выводит FeatureRecipe,
должно быть уникальным для каждого подключения. Здесь оно составляется из хост-компонента
и имени подключения: хост payments-db, подключённый под именем storage-headroom,
даёт PaymentsDbStorageHeadroom.
Одного имени хоста было бы достаточно, чтобы сигнал тревоги не конфликтовал с ресурсом, который он отслеживает, но недостаточно, чтобы одна и та же Feature, дважды подключённая к одному компоненту, не конфликтовала сама с собой, — именно об этом сбойный release ниже.
Собственные свойства сигнала тревоги обращаются к хосту по выведенному имени хоста:
"Properties": { "AlarmDescription": "Free storage below 21474836480 bytes on payments-db", "ComparisonOperator": "LessThanThreshold", "Dimensions": [ { "Name": "DBInstanceIdentifier", "Value": { "Ref": "PaymentsDb" } } ], "EvaluationPeriods": 2, "MetricName": "FreeStorageSpace", "Namespace": "AWS/RDS", "Period": 300, "Statistic": "Minimum", "Threshold": 21474836480, "TreatMissingData": "breaching" },Ref на ресурс базы данных разрешается в идентификатор этого экземпляра при
развёртывании стека. Обе части выводят PaymentsDb из одного и того же имени компонента,
именно поэтому они совпадают — здесь ничего не ищется.
Кто что решает в одном подключении
Подключение разделяет свои входные данные так же, как компонент. Какой запас нужен
приложению — это намерение разработчика, задаваемое в подключении в
aggregate.yaml: это свойство приложения. Куда сигнал тревоги отправляет уведомления
и как долго должен длиться спад, прежде чем он сработает, — это настройка оператора, задаваемая
в Release:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Release задаёт infra для подключения, объявленного в Aggregate, и никогда не задаёт
values. Release с двумя стеками задаёт оба поля, release с одним стеком — ни одного, и
разница видна в выводе. Если задано:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],Если не задано, поле отсутствует, а не пусто: сигнал тревоги создаётся вообще без действия уведомления, а EvaluationPeriods принимает значение 2, заданное в Recipe, а не что-либо объявленное в Feature. Сущность Release, которая не задаёт ни одного из них, всё равно получает рабочий сигнал тревоги, а задание одного добавляет ровно одно поле.
Выводы подключения именуются по его хосту, а не по нему самому
Две части стека именуются по разным правилам, и именно эта часть удивляет пользователей.
Логический ID ресурса берётся из собственного Recipe подключения — это имя выше.
Вывод именуется по публикующему компоненту и записи вместе, а для
подключения публикующим компонентом является хост. Сигнал тревоги публикует одну
запись, alarm-id, и она появляется как:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },Обе части понятны, если знать правило: логический ID допускает только буквы
и цифры, поэтому провайдер записывает словами то, что этот алфавит не допускает, вместо
того чтобы отбросить: Xzh — это написанный вами дефис, а XX — место, где заканчивается имя компонента
и начинается имя записи. К этому имени приводит payments-db, публикующий alarm-id, и
ничто другое. В разделе Имена в собранном
стеке схема
изложена полностью.
Это то же имя вывода, к которому привела бы публикация alarm-id самой базой
данных. Поэтому имя записи, которое публикует и хост, совпало бы с записью
подключения в одном имени вывода, — именно поэтому имена записей, читающиеся как собственные для
подключения, не пересекаются с записями хоста.
Подключение на всю границу отрисовывается один раз для границы
core/shared-config подключается в Release к границе, а не к
компоненту, и отрисовывается один раз для этой границы, а не по разу для каждого компонента в
ней. Сборка с одним стеком содержит два компонента и ровно один AppSharedConfig:
"AppSharedConfig": { [… omitted: the provenance Metadata, whose shape is shown above] "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production" }, "Type": "AWS::SSM::Parameter" },Соберите release с двумя стеками, и это станет ещё нагляднее: каждая граница получает свой экземпляр,
содержащий собственные разрешённые настройки этой границы. Properties экземпляра в
каждом из двух шаблонов, которые записывает эта сборка:
"Properties": { "Description": "Settings shared by every component in the data boundary", "Name": "/data/shared-config", "Type": "String", "Value": "tier=production-data" }, "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production-app" },Оно подключается в Release, потому что содержит собственную конфигурацию оператора,
а не что-либо объявленное в Aggregate. Подключение к границе
задаёт infra: и никогда не задаёт values:: значения разработчика по-прежнему
задаются в Aggregate.
Разделение того же замысла на два стека
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlВ aggregate.yaml ничего не меняется. Приложение по-прежнему объявляет, что использует
базу данных; оператор решает в сущности Release, что они развёртываются
раздельно, и в результате ссылка между ними пересекает границу стека.
В сборке с одним стеком приложение получает адрес подключения как ссылку внутри единственного шаблона:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },В сборке с двумя стеками стек-поставщик публикует это значение как экспорт:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },а стек-потребитель считывает его по тому же имени:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },Export есть только у host, потому что именно эту запись фактически
потребляет ребро; остальные опубликованные записи базы данных выводятся как обычные выходные значения.
Оповещение уровня компонента следует за своим хостом в стек-поставщик, а каждая граница
сохраняет собственное подключение уровня границы.
Ни одна из встроенных функций не вычисляется во время сборки. Адрес подключения не существует, пока стек не развёрнут, поэтому компилятор передаёт ссылку дальше, а CloudFormation разрешает её — именно поэтому приложение никогда не указывает адрес.
О том, как строится имя экспорта и когда потребитель читает через
Fn::ImportValue, а не напрямую между учётными записями, см.
Связывание между стеками.
Сборка, которая останавливается
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml подключает сигнал тревоги дважды к одному компоненту,
под двумя именами подключения. Имя ресурса каждого подключения включает его собственное
имя подключения, поэтому два сигнала тревоги — это два разных ресурса, и здесь они не конфликтуют.
Конфликтуют их выходные значения: каждое публикует alarm-id, выходное значение именуется по
компоненту-хосту и записи, а хост у обоих — один и тот же компонент.
[… omitted: the pull's lines, which report the same collision while writing the lockfile][TRANSLATION_ERROR E0038] dispatch groups whose contributors derive one name more than once in one key space caused by (2): [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation") --- [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")Из этого следуют четыре вывода, и каждый из них сделан намеренно.
- Названы обе стороны. Каждая запись указывает компонент и имя подключения, которое он нёс, поэтому оба можно найти в написанных вами файлах. Ничто в конфликте не делает имя одного из участников предполагаемым, поэтому сообщается об обоих, а не только о первом.
- Названо пространство ключей.
output-logical-idsсообщает, какое из двух пространств имён стека было затронуто, и — поскольку пространство имён ресурсов в этой остановке отсутствует — что с именами ресурсов всё в порядке. - Ничего не выводится. Сборка останавливается, а не записывает стек, в котором один из двух сигналов тревоги молча остаётся без выходного значения.
- Разные имена ресурсов здесь не помогут. Имя выходного значения строится из компонента-хоста и записи, поэтому различаться должна именно запись — либо одно подключение вместо двух, либо Feature, имена опубликованных записей которой читаются как собственные имена этого подключения.
Одинаковые входные данные — одинаковый результат
Две сборки из неизменённых входных данных дают побайтово идентичные шаблоны. Компилятор не обращается к живым данным — он никогда не вызывает AWS, никогда не ищет идентификатор учётной записи и никогда не запускает CloudFormation, — поэтому при повторной сборке нечего обнаружить, что могло бы изменить байты. Именно на этом свойстве основано ревью по diff.
dist/ и файлы *.lock генерируются и не коммитятся; они
генерируются заново из тех файлов, которые коммитятся.