Стек 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— називає реєстр hub, з якого розв’язуються сутності каталогу.
Кожен реліз прив’язує слот 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"} },Лише host має Export, бо саме цей запис фактично споживає ребро;
інші опубліковані записи бази даних з’являються як звичайні виходи. Сигнал тривоги
рівня компонента переходить за своїм хостом у стек-постачальник, а кожна межа
зберігає власне приєднання на рівні всієї межі.
Жодна з вбудованих функцій не обчислюється під час збірки. Кінцевої точки не існує, доки стек не розгорнуто, тому компілятор передає посилання далі, а 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 генеруються й не комітяться; вони
відтворюються з файлів, які комітяться.