Перейти до вмісту
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 — називає реєстр 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 екземпляра.

Усі сутності, які використовує цей приклад, містяться в опублікованому каталозі. Нічого не скопійовано поруч із файлами релізів, тож приклад розв’язується щодо каталогу в його поточному стані, а не щодо його приватного знімка.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

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"}
},

Лише host має Export, бо саме цей запис фактично споживає ребро; інші опубліковані записи бази даних з’являються як звичайні виходи. Сигнал тривоги рівня компонента переходить за своїм хостом у стек-постачальник, а кожна межа зберігає власне приєднання на рівні всієї межі.

Жодна з вбудованих функцій не обчислюється під час збірки. Кінцевої точки не існує, доки стек не розгорнуто, тому компілятор передає посилання далі, а 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 генеруються й не комітяться; вони відтворюються з файлів, які комітяться.