Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Стек 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 экземпляра.

Все сущности, которые использует этот пример, находятся в опубликованном каталоге. Ничего не копируется рядом с файлами релизов, поэтому пример разрешается относительно каталога в его текущем состоянии, а не относительно его частного снимка.

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

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

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

Terminal window
aggrega scaffold --example cloudformation-rds-stack

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd cloudformation-rds-stack

Сборка

В этом примере три релиза, поэтому укажите нужный. За один запуск собирается один релиз. Первой сборке каждого релиза нужен его lock-файл, который записывает pull:

Terminal window
aggrega pull --release release-one-stack.yaml
aggrega build --release release-one-stack.yaml

Сборка выводит следующее (<workspace> обозначает папку этого примера):

Total build time: 4.1s
Build 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.

Разделение того же замысла на два стека

Terminal window
aggrega pull --release release-two-stacks.yaml
aggrega 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, а не напрямую между учётными записями, см. Связывание между стеками.

Сборка, которая останавливается

Terminal window
aggrega pull --release release-negative-name-collision.yaml
aggrega build --release release-negative-name-collision.yaml

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