Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

CloudFormation Provider

Провайдер cloudformation рендерить сутності Aggrega Recipes у шаблони стеків AWS CloudFormation. Кожен компонент, що рендериться в той самий вихідний каталог цим провайдером, збирається в один стек, який виводиться як єдиний шаблон на чистому JSON із довгою формою вбудованих функцій. Тому межа у звичайному випадку стає одним стеком — а дві межі, чий directory: розв’язується в той самий шлях, разом збираються в один стек і спільно використовують імена цього шаблону. Як і кожен провайдер Aggrega, він працює офлайн і герметично — збірка Aggrega є компіляцією наперед (ahead-of-time), тож провайдер ніколи не звертається до AWS, ніколи не розв’язує ідентифікатори, згенеровані обліковим записом, і ніколи не запускає CloudFormation. Значення, доступні лише під час виконання, залишаються посиланнями на вбудовані функції CloudFormation (Fn::GetAtt, Fn::ImportValue, Fn::GetStackOutput), які CloudFormation розв’язує під час розгортання.

Recipes-фрагменти, зібрані в стек

Сутність Recipe для cloudformation описує фрагмент — ресурси CloudFormation, які додає один компонент, — а не цілий шаблон. Коли компоненти межі рендеряться, провайдер збирає кожен фрагмент групи диспетчеризації в один шаблон стека: ресурси об’єднуються в одній мапі Resources, значення provides кожного компонента з’являються як Outputs стека, а решту розділів верхнього рівня шаблону розглянуто по черзі в розділі Розділи верхнього рівня в зібраному стеку. Приймаються дві форми опису:

  • Вхід-фрагмент (артефакти). Сутність Recipe безпосередньо описує фрагменти ресурсів; провайдер нормалізує їх до чистого JSON із довгою формою вбудованих функцій і об’єднує їх у зібраний стек.
  • Вхід із джерела. Сутність Recipe посилається на наявний шаблон CloudFormation (YAML або JSON); провайдер нормалізує його до JSON із довгою формою, перевіряє його структуру перед збиранням, заповнює параметри, які оголошує шаблон, з valuesMapping сутності Recipe — див. Значення для параметрів шаблону з джерела — і пропускає кожен ресурс, названий у записах omits: сутності Recipe, — див. Пропуск ресурсів у шаблоні з джерела.

Зібраний шаблон — це чистий JSON. Вбудовані функції виводяться дослівно й ніколи не обчислюються під час збирання — компілятор не може визначити значення, яке існує лише після розгортання стека, а обчислення такого значення порушило б контракт попередньої компіляції.

Feature, приєднана до компонента, додає вміст до того самого стека

Сутність Feature, приєднана до компонента, додає свої ресурси до стека, у який збирається її компонент-хост, на тих самих умовах, що й власна сутність Recipe компонента-хоста. Окремого шаблону поруч немає: зібраний стек — це все, що цей провайдер виводить для каталогу виводу, тож ресурси приєднаної Feature або є в цьому стеку, або не розгортаються взагалі. Від’єднання Feature вилучає саме ці ресурси й залишає власні ресурси компонента-хоста недоторканими.

Оскільки вони потрапляють до зібраного стека, вони поділяють його імена. Логічні ID ресурсів приєднаної Feature перебувають у тому самому просторі, що й ID компонента-хоста та кожної іншої Feature, приєднаної поруч із нею, тож розділ Імена в зібраному стеку застосовується до них без змін. Коли два учасники збігаються на одному імені, зупинка називає компонент і ключ, під яким приєднано Feature, тож обидва кінці колізії можна знайти пошуком у ваших власних файлах.

Виходи приєднаної Feature публікуються під іменем її компонента-хоста, а логічні ID її ресурсів — ні. Дві половини стека іменуються за різними правилами, тож відповідають на це по-різному. Логічний ID ресурсу виводиться точно так, як його описала сутність FeatureRecipe, як і в будь-якої Recipe. Вихід називається за компонентом, що публікує, разом із записом — а для Feature, приєднаної до компонента, компонентом, що публікує, є хост: Feature, приєднана до payments-db, яка публікує alarm, отримує paymentsXzhdbXXalarm — те саме ім’я, яке отримав би запис, якби компонент-хост опублікував його сам. Тож ім’я запису, яке публікує й хост, збігається з ім’ям запису приєднання в одному імені виходу, і збирання зупиняється, називаючи компонент і ключ, під яким приєднано Feature, поряд із самим компонентом. Вибір імен записів, які читаються як власні для Feature, — backup-alarm замість alarm — запобігає їхньому збігу з іменами хоста.

Кожен ресурс, який додає Feature, зберігає в походженні, яке збирання записує в нього, ідентичність, складену для цього приєднання, а не ідентичність компонента-хоста, тож їх можна розрізнити всередині стека, до якого додали вміст обидва. Розділ Мітки й анотації описує, як будується ця ідентичність.

Розділи верхнього рівня у зібраному стеку

Кілька компонентів збираються в один стек, тому збирання має врахувати кожен розділ верхнього рівня, який допускає шаблон CloudFormation, — зокрема Globals і Hooks, два розділи, які додають до мови шаблонів трансформації, що їх розміщує CloudFormation. Кожен із них належить рівно до однієї з груп нижче, а для ключа верхнього рівня, який пише компонент і який не є жодним розділом, видається попередження з назвою компонента й ключа, тож нічого не відкидається мовчки.

Збираються під іменами, область яких визначає провайдер, або читаються як написано. Resources і Outputs, які повністю описано в розділі Імена у зібраному стеку. AWSTemplateFormatVersion пише провайдер, а не читає з будь-якого компонента: мова шаблонів допускає для нього одне значення, тож компоненту нічого вирішувати.

Переносяться саме під тими іменами, які ви написали. Parameters, Mappings, Conditions, Metadata і Rules. Кожен із них — це мапа з ключами-іменами, які вибрали ви, тож записи кожного компонента потрапляють у зібраний стек під цими іменами без переписування — саме це дає змогу Condition: ресурсу, Fn::FindInMap чи Ref на параметр розв’язатися щодо оголошення, яке надійшло разом із ним. Кожен переноситься окремо, бо кожен пишеться окремо: правило перевіряє параметр того самого документа, умова може взагалі не посилатися на параметр, а CloudFormation не дозволяє посилатися на параметр усередині мапи.

Одне слово тут позначає два різні місця, і лише перше з них належить вам. Metadata у списку вище — це власний розділ верхнього рівня шаблону, мапа імен, які вибрали ви. Окремий ресурс також має власний атрибут Metadata, і саме туди збирання записує походження — під одним зарезервованим ключем aggrega.ai/, який додається поруч із тим, що ви там написали, а не замінює його. Тож запис про походження всередині ресурсу — це не те, що написали ви, і не те, що переніс розділ верхнього рівня.

Parameters, Mappings, Conditions і Rules іменують свої записи логічним ідентифікатором. Оскільки провайдер переносить ім’я саме так, як ви його написали, абетка, яку допускає логічний ідентифікатор, поширюється і на ці розділи: ім’я в одному з цих чотирьох, що містить щось, окрім літер і цифр, зупиняє збирання — див. A carried section name outside the alphabet halts (Перенесене ім’я розділу поза абеткою зупиняє збирання). Провайдер не вимагає цієї абетки від імен розділу верхнього рівня Metadata: вони іменують інформацію, яку ви зберігаєте, а не те, до чого звертається шаблон.

Якщо два компоненти оголошують різні імена в одному з цих розділів, потрапляють обидва. Якщо два оголошують одне ім’я з ідентичним вмістом, вони зливаються в один запис і збирання триває. Якщо два оголошують одне ім’я з різним вмістом, збирання зупиняється з назвою розділу, імені та обох компонентів — бо інакше одне з двох тіл було б відкинуто, і компонент, який його написав, мав би оголошення, якого стек не містить. Це те саме узгодження, якого дотримуються імена ресурсів і виходів, і перейменування будь-якого з них усуває конфлікт.

Називаються, а не переносяться. Description — це одне твердження про весь шаблон, а не мапа імен, які вибрали ви, тож збирання з кількох компонентів не має для нього відповіді: два описи — це дві відповіді на одне питання, і жоден не є описом стека. Hooks читає лише трансформація AWS::CodeDeployBlueGreen, якої зібраний стек ніколи не містить (див. нижче). Тому зібраний стек не містить жодного з них, і кожен компонент, що написав один із них, отримує попередження з назвою компонента й розділу. Так само й компонент, що пише Globals, не оголосивши трансформації AWS::Serverless-2016-10-31, яка його читає. Попередження має рекомендаційний характер і видається поза основним виводом: згенерований шаблон байт у байт такий самий, яким був би без нього, а --no-unsupported-field-warnings вимикає його разом з рештою цього класу.

Transform будується з трансформацій усіх компонентів. Трансформація — це макрос, який CloudFormation виконує над усім шаблоном перед розгортанням будь-чого, тож Transform зібраного стека — це об’єднання трансформацій, які оголошують його компоненти, — як вихідного шаблону, так і фрагмента, — у порядку, який документує CloudFormation: макрос, визначений вашим обліковим записом, перед трансформаціями, які розміщує CloudFormation, і AWS::LanguageExtensions перед AWS::Serverless-2016-10-31. Власний порядок кожного компонента зберігається, а дві трансформації, яких ніщо не впорядковує, виконуються в порядку, у якому компоненти вперше їх оголошують, тож ті самі компоненти дають той самий стек. Одна трансформація записується рядком, кілька — списком. Стек лише з одним компонентом, який оголошує свій Transform в одному шаблоні чи фрагменті, зберігає його саме так, як його написано, скрізь, де таблиця нижче його переносить, а стек, компоненти якого не оголошують жодної, не містить жодної. Трансформація компонента не викликає попередження: вона переноситься, або збирання зупиняється з її назвою.

Оскільки трансформація обробляє весь шаблон, її перенесення змінює те, як розгортається вміст кожного іншого компонента, якщо її дія не обмежена вмістом, написаним для неї. Тож кожна трансформація отримує те розпорядження, яке підтримує власна документація CloudFormation щодо неї, а комбінація, якої стек не може містити, зупиняє збирання з назвою трансформації та кожного компонента стека:

трансформаціяу зібраному стеку
AWS::Serverless-2016-10-31переноситься разом із Globals компонента, що її оголошує. Зупиняє збирання, коли ці Globals досягли б безсерверних ресурсів іншого компонента, а також коли джерело подій одного з її ресурсів називає ресурс, оголошений іншим компонентом, бо трансформація переписує ресурс, який називає подія.
AWS::LanguageExtensionsпереноситься сама або поруч із AWS::Serverless-2016-10-31 з того самого компонента. Зупиняє збирання поруч із безсерверним вмістом іншого компонента, бо безсерверна трансформація інакше називає те, що генерує, після того як мовні розширення розв’язали її значення.
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16переносяться: вони обробляють лише ті розклади ротації, які їх запитують.
AWS::ServiceCatalogпереноситься для стека лише з одним компонентом. Поруч із будь-яким іншим зупиняє збирання, бо підставляє свій шаблон посилання будь-де в шаблоні.
AWS::CodeDeployBlueGreenзупиняє збирання навіть сама: CloudFormation відхиляє Outputs і Fn::ImportValue будь-де в шаблоні, що її оголошує, а зібраний стек містить виходи, які публікують його компоненти.
AWS::Includeзупиняє збирання навіть сама: вона вставляє вміст, отриманий з S3 під час розгортання стека, якого збирання не може прочитати.
макрос, визначений вашим обліковим записомпереноситься для стека лише з одним компонентом. Поруч із будь-яким іншим зупиняє збирання, бо збиранню невідомо, що він робить з рештою шаблону.

Два компоненти, що оголошують одну пару трансформацій у протилежному порядку, теж зупиняють збирання з назвою обох порядків і обох компонентів, оскільки стек виконує їх в одному порядку. Компонент, якому потрібна трансформація, якої стек не може містити, розміщується в окремій межі.

Імена в зібраному стеку

Логічний ідентифікатор CloudFormation унікальний у межах одного шаблону й допускає лише літери та цифри, а всі компоненти, що збираються в цей шаблон, спільно використовують його імена — зокрема компоненти з другої межі, коли обидві межі ведуть до того самого вихідного каталогу. Тому кожне ім’я, за яким стек до чогось звертається, має бути унікальним серед усіх компонентів, що його внесли, а множина учасників не завжди обмежується однією межею.

Логічні ідентифікатори ресурсів походять із сутності Recipe. Провайдер виводить їх точно так, як їх записано, і жодного не переписує, тож ім’я, яке ви бачите в зібраному шаблоні, — це ім’я, яке записала сутність Recipe. Стандартні бібліотечні CloudFormation Recipes виводять його з власного імені екземпляра компонента, сприймаючи роздільники в цьому імені як межі слів: екземпляр payments-db називає свій ресурс PaymentsDb. Тому два екземпляри одного типу описують два ресурси, а не змагаються за один.

Імена виходів обмежуються областю компонента, що їх опублікував. Кожен запис provides з’являється як вихід, названий за компонентом-публікатором і записом разом — компонент payments-db, що публікує host, з’являється як paymentsXzhdbXXhost, — тож два компоненти, що публікують той самий запис, потрапляють у два окремі виходи, а значення виходу не змінюється, коли до стека долучається інший компонент. Міжстековий споживач у тому самому обліковому записі й регіоні імпортує за іменем експорту, а не за цим іменем, тож ім’я експорту не змінюється; читання з іншого облікового запису чи регіону вказує цей вихід — провайдер записує його за вас (див. Міжстекове зв’язування).

Як будується ім’я виходу

Логічний ідентифікатор не допускає жодного символу-роздільника, тож ім’я, побудоване з того, що ви написали, мусить якось перенести ваші роздільники. Відкидати їх означало б втрачати інформацію: payments-db і payments_db — це два компоненти, а ім’я без розділових знаків не ідентифікувало б жодного з них. Тому провайдер натомість кодує те, що алфавіт відкидає, записуючи кожен недопустимий символ символами, які алфавіт допускає.

Схема резервує один символ для початку екранування — велику X — а все інше записує так, як ви це набрали, включно з великими літерами. Зарезервовано лише велику літеру, тож мала x в імені на кшталт nginx-proxy переноситься так, як ви її написали:

що ви написалина що це перетворюєтьсячому
літера або цифра, крім Xзалишається собоюалфавіт її допускає
-Xzhалфавіт не допускає дефіс
_Xzuалфавіт не допускає підкреслення
.Xzdалфавіт не допускає крапку
/Xzsалфавіт не допускає скісну риску, яку містить ідентичність вкладеного компонента
XXzx000058зарезервована для початку екранування, тому записується кодовою точкою
будь-що іншеXzx і кодова точка символуодне правило охоплює всі решту символів
місце зʼєднання двох половинXXдва початкові символи поспіль, яких не може містити жодна з половин

Зворотне читання однозначне, і в цьому суть, а не просто зручність. X зберігається як є лише тоді, коли наступний символ допускається алфавітом, тож закодована половина ніколи не закінчується нею й ніколи не містить двох поспіль — завдяки цьому XX може означати зʼєднання, і тільки його.

Отже, три імені, що відрізняються лише розташуванням розділових знаків, залишаються різними:

component payments-db publishing host → paymentsXzhdbXXhost
component payments_db publishing host → paymentsXzudbXXhost
component payments publishing db-host → paymentsXXdbXzhhost

Імена довші й менш зрозумілі з першого погляду, ніж написане вами ім’я компонента, і це свідомий компроміс. Ім’я, що ідентифікує рівно один запис, цінніше за коротше, яке не ідентифікує жодного з двох, — а до виходу ви звертаєтеся через ім’я експорту, а не набираючи це ім’я, тож ціна полягає лише в повторному погляді під час читання виведеного шаблону.

Для логічних ідентифікаторів ресурсів діє інше правило, бо провайдер їх не будує: він виводить те, що записала сутність Recipe. Стандартні бібліотечні CloudFormation Recipes виводять ідентифікатор, сприймаючи роздільники в імені екземпляра як межі слів — екземпляр payments-db називає свій ресурс PaymentsDb, — і таке виведення відкидає роздільники, тож два імені екземплярів, що відрізняються лише розділовими знаками або лише регістром літери, усе одно дають одне ім’я ресурсу. Збірка зупиняється, називаючи кожен екземпляр, що дійшов до цього імені, разом із самим іменем, замість того щоб вивести один ресурс там, де оголошено два компоненти. Називаються всі, а не деякі, бо ніщо в колізії не робить виведення одного екземпляра задуманим. Перейменування всіх, крім одного, усуває проблему.

Логічний ідентифікатор ресурсу поза алфавітом зупиняє збірку

Унікальність і алфавіт — дві окремі вимоги, і набір імен може задовольняти першу й порушувати другу. Оскільки провайдер виводить логічний ідентифікатор ресурсу точно так, як його записала сутність Recipe, ідентифікатор, який створює Recipe, мусить бути таким, що шаблон CloudFormation може його містити сам по собі: літери й цифри, і нічого більше.

Саме тут шляхи виведеного й переданого без змін імені розходяться. Ім’я виходу будує провайдер, який кодує компонент-публікатор і запис, тож ім’я виходу лежить у межах алфавіту, хоч як ви запишете будь-яку з половин. Логічний ідентифікатор ресурсу передається без змін, тож шаблон отримує саме те, що записала сутність Recipe.

Це робить його обмеженням і для імен компонентів, щоразу коли Recipe записує ім’я екземпляра компонента безпосередньо в логічний ідентифікатор. Ім’я компонента може містити дефіс або підкреслення; логічний ідентифікатор — ні. Тому компонент, який ви спрямовуєте на цей провайдер через таку сутність Recipe, називається лише літерами й цифрами — paymentsdb, а не payments-db, — а будь-що інше зупиняє збірку.

Повідомлення про зупинку називає учасника, чия сутність Recipe створила ідентифікатор, сам ідентифікатор і кожен недопустимий у ньому символ, а також підказує, що можна написати натомість. Усунути проблему можна двома способами, і перший доступний вам завжди:

  • Нехай сутність Recipe створює власний логічний ідентифікатор, а не передає ім’я без змін. Саме так роблять стандартні бібліотечні CloudFormation Recipes — вони сприймають роздільники в імені екземпляра як межі слів, тож екземпляр payments-db називає свій ресурс PaymentsDb, а ви зберігаєте обране ім’я компонента. Виведення ідентифікатора таким способом замінює цю зупинку правилом колізій, описаним вище: два імені екземплярів, що відрізняються лише розділовими знаками, дають одне ім’я ресурсу.
  • Якщо Recipe все ж передає ім’я без змін, перейменуйте те, що вона передає, використовуючи лише літери й цифри. Для власної сутності Recipe компонента це ім’я компонента. Сутність Feature, приєднана до компонента, називає свої ресурси з власної сутності FeatureRecipe, тож перейменування компонента-господаря їх не зачіпає — змінити потрібно ідентифікатор, який записує ця Recipe.

Провайдер відмовляє; він не виправляє непомітно. Переписати ідентифікатор за вас здавалося б корисним, але це не так. Логічний ідентифікатор — це те, за чим CloudFormation ідентифікує ресурс між оновленнями, тож його зміна — не перейменування, а звернення до іншого ресурсу. Ідентифікатор, підставлений провайдером, указував би не на ресурс, уже розгорнутий під написаним вами ідентифікатором, а підстановку, про яку ви не просили, довелося б виявляти у виведеному шаблоні. Збірка, що зупиняється, називає проблему, поки її ще можете виправити ви.

Перенесене ім’я секції поза алфавітом зупиняє збирання

Логічні ідентифікатори ресурсів — не єдині імена, які провайдер переносить точно так, як ви їх написали. Parameters, Mappings, Conditions і Rules теж іменують свої записи логічним ідентифікатором, і кожна з чотирьох секцій потрапляє до зібраного стека під іменем, яке обрав її автор. Тож вимога та сама, лише на чотирьох додаткових поверхнях: ім’я має бути таким, яке шаблон CloudFormation може містити самостійно, — літери й цифри, і нічого більше, — а будь-що інше зупиняє збирання.

Є один наслідок, що виходить за межі секції, яка містить ім’я, і саме через нього збирання зупиняється, а не попереджає. Саме за цими іменами розв’язуються Condition: ресурсу, Fn::FindInMap чи Ref на параметр. Тому ім’я, якого алфавіт не допускає, виводить із придатного до розгортання шаблону і посилання на нього, і саме оголошення, тож одне написане ім’я робить обидва недосяжними одночасно, — а без зупинки це виявилося б під час розгортання, і виявив би це той, хто розгортає, а не той, хто написав ім’я.

Зупинка називає учасника, чий Recipe написав ім’я, секцію, у якій його написано, саме ім’я та кожен символ у ньому, якого там не може бути. Саме секцію слід шукати у ваших Recipes: ці імена переносяться саме під тією секцією, у якій ви їх написали, тож це єдине слово, яке з’являється і в повідомленні, і у ваших власних файлах. Перейменування запису лише літерами й цифрами усуває проблему, і це весь спосіб її розв’язати: для логічного ідентифікатора ресурсу є альтернатива — щоб Recipe виводив ідентифікатор замість передавати ім’я напряму, — а тут виводити нічого, бо ім’я в секції і є тим, що ви написали.

Алфавіту мають відповідати лише власні імена секції, а не ключі всередині запису. Ключі другого рівня у відображенні ви обираєте вільно: us-east-1 у відображенні RegionCidr — звичайний випадок, і він потрапляє до згенерованого шаблону без змін. Ключі в тілі параметра, умови чи правила іменують атрибути, твердження та вбудовані функції, а не щось, до чого звертається стек: Assertions правила і Fn::Contains, написана в ньому, — ключі саме такого роду. Жоден із них не є логічним ідентифікатором, і жоден не перевіряється.

Два імена записів, які ви написали по-різному, залишаються різними

Три види імен записів розташовані досить близько, щоб зійтися в одному імені виводу, і жоден із них не екзотичний. Оскільки дві половини кодуються, а не згортаються, і з’єднуються послідовністю, якої жодна половина не може містити, усі три отримують власні імена:

  • Записи, що відрізняються лише пунктуацією. Компонент, який публікує і db-host, і db_host, отримує dbXzhhost і dbXzuhost.
  • Записи, що відрізняються лише регістром літери. host і Host дають host і Host, бо літера переноситься в тому регістрі, у якому ви її написали.
  • Записи, що зустрічаються на місці з’єднання. Component payments-db, що публікує host, отримує paymentsXzhdbXXhost; Component payments, що публікує db-host, отримує paymentsXXdbXzhhost.

Два записи все ж сходяться там, де вони справді іменують одне й те саме. Ім’я виводу будується з компонента-публікатора й запису, тож усе, що має спільними обидва, отримує одне ім’я, хоч як його закодовано. Найімовірніший випадок — одна сутність Feature, приєднана двічі до одного компонента: приєднання публікує під своїм хостом, тож два приєднання однієї Feature до одного компонента обидва публікують alarm-id від payments-db, і в цій парі немає нічого, що їх розрізняло б. Збирання зупиняється, а не генерує один вивід там, де написано два, і називає компонент і ключ приєднання, який несла кожна сторона, тож обидва кінці можна знайти у ваших власних файлах. Або приєднайте Feature один раз, або використайте Feature, імена опублікованих записів якої читаються як власні для цього приєднання.

Це справджується незалежно від того, чи мають два записи однакове значення. Два записи з однаковим значенням усе одно описують два виводи, яких хотів автор, тож злиття їх в один залишило б один із двох написаних виводів відсутнім у стеку.

Ім’я, яке Recipe складає в шаблоні, цим не охоплюється

Описане вище кодування належить провайдеру й застосовується до імен виводів, які будує провайдер. Воно недоступне вам усередині шаблону Recipe, тому ім’я, яке складає ваш шаблон, не має жодної з його гарантій. Сказати це прямо важливо, бо зсередини шаблону небезпеки не видно: доступне там згортання читає свій аргумент як слова й відкидає все між ними, тож з’єднання двох значень перед згортанням втрачає з’єднання разом із пунктуацією.

FeatureRecipe, що іменує ресурс за екземпляром і ключем приєднання, з’єднаними пробілом і потім згорнутими, — саме та форма, за якою слід стежити: app із cache і app-cache без нічого обидва згортаються в AppCache, і вони конфліктують ще до того, як застосовується будь-яка властивість згортання. Відмінність такого імені забезпечують дві речі, і обидві — ваша справа, а не провайдера:

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

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

Ключ, написаний двічі в одному відображенні, зупиняє збирання

Фрагмент CloudFormation читається як відображення, а відображення містить одне значення на ключ, тож ключ, написаний двічі, зберіг би тіло, що йшло останнім, і відкинув би інше. Якщо відображення — це блок Resources чи Outputs, відкинуте тіло — це ресурс або вивід, який було написано і якого просто не було б у стеку.

Натомість збирання зупиняється й називає повторений ключ і обидва рядки, у яких його написано. Це правило для всього фрагмента, а не правило про імена стека: воно застосовується до будь-якого відображення у фрагменті, зокрема до Properties ресурсу. Найчастіше до нього доходить Recipe, що виводить логічний ідентифікатор із написаного значення, коли два написані значення відрізняються лише пунктуацією: app-cache і app_cache обидва дають AppCache, тож фрагмент пише AppCache двічі.

Ім’я ключа, що повторюється в різних місцях документа, — звичайна річ, і його не зачіпають: Type з’являється один раз на ресурс, а Value — один раз на вивід, хоч скільки ресурсів і виводів містить фрагмент. Тіло втрачає лише повтор усередині одного відображення.

Один компонент може заявити одне ім’я двічі. Recipe додає кілька фрагментів — кілька записів artifacts: або вихідний каталог із кількома шаблонами, — і кожен із них збирається в той самий стек, тож власні фрагменти компонента поділяють імена стека між собою так само, як вони поділяють їх між компонентами. Два фрагменти, що дають одному імені два різні тіла, зупиняють збирання, і зупинка називає простір ключів, у якому лежить ім’я, — логічні ідентифікатори ресурсів чи імена виводів, — разом із компонентом і самим ім’ям. Обидва простори досяжні в такий спосіб: два фрагменти можуть написати один логічний ідентифікатор ресурсу для різних ресурсів, а компонент доходить до своїх імен виводів двома шляхами, явним блоком Outputs: і своїми записами provides:, тож запис із кожного з них з одним ім’ям також зустрічається там.

Повторне зазначення імені саме по собі не є конфліктом. Ім’я, написане більше одного разу з ідентичним вмістом, так чи інакше адресує одну річ, тож повтори зливаються в один запис і збирання продовжується: звичайний повтор нічого не коштує. Зупиняє збирання випадок, що втрачає вміст: одне з двох тіл довелося б відкинути, і тоді ресурс чи вивід, оголошений Recipe, був би відсутній у стеку. Перейменування будь-якого з них усуває проблему.

Структурна перевірка вхідних даних

Шаблон CloudFormation, отриманий із джерела, проходить структурну перевірку перед рендерингом: provider розбирає шаблон і нормалізує його вбудовані функції, а якщо шаблон має неправильну форму, зупиняє збирання зі зрозумілим повідомленням, яке називає проблемний вузол. Розбір перевіряє форму, а не семантику: він не звертається до AWS, не розв’язує посилання й не обчислює вбудовані функції.

Те, що шаблон успішно розібрано, ще не означає, що його перенесено повністю. Розбір підтверджує, що документ правильно сформований; що саме потрапить до зібраного стека, вирішується окремо й для кожного розділу, як описано в Розділи верхнього рівня в зібраному стеку: шаблон із джерела проходить той самий облік, що й фрагмент.

Розбір також не перевіряє, чи розв’язуються посилання шаблону. Чи називає Ref параметр, а Fn::FindInMap — мапу, — це питання про зібраний стек, а не про окремий вхідний документ, і відповідає на нього CloudFormation під час розгортання. Замість того щоб оцінювати, на що посилається результат, збирання повідомляє, чого воно не перенесло. Оцінює воно лише ті посилання, які саме збирання зробило висячими: посилання на параметр, заповнений прив’язкою шаблону з джерела, — про це йдеться в наступному розділі, — і посилання на ресурс, який запис omits: вилучив із шаблону, — про це йдеться в розділі після нього.

Значення для параметрів шаблону з джерела

Шаблон з джерела отримує значення так само, як їх отримує шаблон у самому CloudFormation: через оголошені в ньому Parameters. valuesMapping того, що є його джерелом, — Recipe компонента або FeatureRecipe приєднаної сутності Feature, — записує по одному ключу на кожен параметр, який заповнює, і провайдер прив’язує кожен із них у кожному шаблоні джерела: кожен Ref на параметр у Resources, Outputs, Conditions, Rules і Globals SAM стає значенням, кожен Fn::Sub, що називає параметр як змінну, отримує значення через свою мапу змінних, а параметр зникає з Parameters кожного шаблону, що його оголошує. Параметр, який не названо жодним ключем, залишається точно таким, яким його записано в шаблоні, — для значення, переданого під час розгортання стека, або для його Default.

Параметр оголошує джерело як ціле. Шаблони джерела-каталогу збираються в один стек, тож один шаблон може посилатися на параметр, оголошений іншим шаблоном того самого джерела. Заповнення параметра заповнює його й там: шаблон, який лише посилається на нього, отримує значення в тому перетворенні, яке виконав перший шаблон джерела, що його оголошує, і в джерелі не залишається жодного посилання на параметр, оголошення якого прибрала прив’язка.

Ніщо інше в стеку не може посилатися на заповнений параметр. Вміст поза джерелом — фрагмент або шаблон з джерела іншого компонента в тому самому стеку, — який називає параметр, заповнений прив’язкою джерела, через Ref, змінну Fn::Sub або Fn::ValueOf правила, називав би те, чого зібраний стек уже не оголошує, і CloudFormation відхилить це під час розгортання стека. Тому збірка зупиняється, називаючи кожен компонент, його шаблон і параметр, а також компонент, чий valuesMapping його заповнив, — сутності Recipe або FeatureRecipe приєднаної сутності Feature; Feature, приєднану до компонента, називають за цим компонентом, а приєднану до межі — за ідентичністю, яку її ресурси несуть як aggrega.ai/component-id, складеною зі шляху межі та імені приєднання (bfr--stack--aux для приєднання aux на межі stack). Фрагмент компонента, до якого приєднано Feature, або компонента в межі, до якої її приєднано, що посилається на параметр, заповнений прив’язкою приєднання, теж зупиняє збірку. Ім’я, яке стек і далі оголошує, це не зачіпає: якщо інший компонент сам оголошує параметр із таким ім’ям або ресурс має його як логічний ID, посилання на нього розв’язуються до цього оголошення й залишаються як записано. Щоб передати значення далі, нехай компонент, що заповнює, опублікує його, оголосіть параметр у шаблоні, який на нього посилається, або приберіть ключ із valuesMapping.

spec:
capability: cloudformation
implements: core/delivery-stream:1.0.0
source:
kind: git-repository
url: https://github.com/aws-cloudformation/aws-cloudformation-templates.git
ref: a0f43bc6d20813052892546f445037cf84c75b54
module_subdir: DataFirehose
valuesMapping: |
CloudWatchLogGroupRetention: {{ .values.retention_days }}
DestinationBucketName: "{{ .context.inject.env.BUCKET_NAME }}"

Параметри заповнює лише valuesMapping. Ключі, які він записує, — це імена параметрів, призначені вами для шаблону, тож кожен має називати параметр, оголошений якимось шаблоном джерела: ключ, що не називає жодного, зупиняє збірку, а повідомлення називає ключ і параметри, які оголошує кожен шаблон, — це та помилка, яку CloudFormation повідомив би про невідомий параметр, але повідомлена тоді, коли ви ще можете її виправити. Сутність Recipe або FeatureRecipe, що не оголошує valuesMapping, нічого не заповнює: власні значення компонента чи приєднання надходять до провайдера під своїми іменами, записаними для інших його вхідних даних, і не зчитуються.

Те, що надходить до шаблону, залежить від того, чим є значення.

  • Літерал — рядок, число, булеве значення або їхній список — записується в шаблон у перетворенні, яке CloudFormation застосовує до того самого значення, переданого для Type параметра під час розгортання стека: Number стає рядком, який дає Ref на нього, тож 7 надходить як "7"; тип CommaDelimitedList або List<…> стає списком рядків і приймає або список, або рядок через кому, елементи якого обрізаються; кожен інший тип приймає один рядок. Літерал перевіряється на власні AllowedValues, AllowedPattern, MinLength, MaxLength, MinValue і MaxValue параметра, а літерал, який вони відхиляють, зупиняє збірку з назвою параметра й обмеження, тож заповнення параметра не прибирає жодної перевірки, оголошеної в шаблоні. Шаблон, записаний у синтаксисі регулярних виразів, який збірка не може прочитати, залишається для перевірки CloudFormation під час розгортання стека.
  • Значення, яке повністю є однією вбудованою функцією CloudFormation, надходить у місце посилання як ця функція, щоб CloudFormation обчислив її під час розгортання стека: мапа в довгій формі, як-от {"Fn::GetAtt": [Queue, Arn]}, або рядок, що є рівно однією короткою формою, — !GetAtt Queue.Arn, !Ref Bucket, !Sub … та інші форми, визначені CloudFormation. Саме так опубліковане посилання іншого компонента досягає параметра: Recipes каталогу для CloudFormation публікують таке посилання як текст у короткій формі, а valuesMapping, що зчитує його з контексту ін’єкції, передає його далі. Вставлене посилання читається однаково в лапках і без них. У лапках — "{{ .context.inject.env.BUCKET_NAME }}" — мапінг передає рядок !GetAtt Queue.Arn; без лапок власний YAML мапінгу читає !GetAtt Queue.Arn як тег, і тег зберігається разом зі своїм аргументом, а не відкидається. В обох випадках до параметра надходить вбудована функція. Значення, яке лише починається зі знака оклику або не називає жодної короткої форми CloudFormation, залишається текстом.
  • Динамічне посилання — {{resolve:ssm:…}}, {{resolve:ssm-secure:…}} або {{resolve:secretsmanager:…}} — надходить у місце посилання як записано, щоб CloudFormation розв’язав його під час розгортання стека, тож значення, яке воно називає, ніколи не потрапляє в шаблон.
  • Значення, яке інший компонент публікує з іншого стека, надходить до шаблону як міжстекове посилання — той самий Fn::ImportValue або Fn::GetStackOutput, що отримує фрагмент (див. Міжстекове з’єднання), — у кожне місце, де шаблон посилався на параметр.

Для параметра, тип якого CloudFormation зчитує з Parameter Store, — AWS::SSM::Parameter::Value<…> — немає літерала, що відтворює те, що CloudFormation зробив би з ним, тож прив’язаний до нього літерал зупиняє збірку; прив’яжіть посилання {{resolve:ssm:…}} або вбудовану функцію чи залиште його неприв’язаним. Список, прив’язаний до параметра, який шаблон називає як змінну Fn::Sub, теж зупиняє збірку, бо змінна підставляє один рядок. Ключ, який valuesMapping встановлює в null, так само зупиняє збірку з назвою параметра, бо параметр приймає значення, а null значенням не є; щоб залишити параметр для значення, переданого під час розгортання стека, або для його Default, не включайте його ключ у мапінг.

Правило, що зчитує параметр за іменем, залишає його неприв’язаним. Fn::ValueOf у Rules шаблону називає оголошений параметр за його логічним ID, а не через Ref, а заповнення параметра прибирає його оголошення, тож прив’язка параметра, який правило зчитує в такий спосіб, зупиняє збірку з назвою правила й параметра.

Літерал, що може містити секрет, відхиляється; вбудована функція записується як подано. Значення, записане в шаблон, може прочитати кожен, хто може прочитати шаблон стека:

  • Параметр, який шаблон оголошує NoEcho, приймає динамічне посилання або вбудовану функцію, а прив’язаний до нього літерал зупиняє збірку.
  • Якщо valuesMapping зчитує значення, яке автор оголосив чутливим, жоден його результат не можна відстежити до значення, з якого він походить, тож кожен прив’язаний ним літерал зупиняє збірку. Прив’язані ним динамічне посилання та вбудована функція записуються як подано — разом із текстом усередині вбудованої функції. Тому секрет, який мапінг вставляє, скажімо, у текст Fn::Sub, потрапляє в шаблон як цей текст: лише динамічне посилання не допускає сам секрет у шаблон. Якщо така збірка продовжується, вона також виводить по одному попередженню на кожен оголошений лист — однаково для мапінгу сутності Recipe і для мапінгу FeatureRecipe сутності Feature, приєднаної до компонента, — з назвою листа й сутності, якій належить мапінг, — див. A declared-sensitive value reaches the target through a values mapping (Значення, оголошене чутливим, досягає цілі через мапінг значень).
  • Динамічне посилання зупиняє збірку, якщо на його параметр посилаються у властивості UserData ресурсу, у метаданих AWS::CloudFormation::Init або в Outputs: CloudFormation не розв’язує динамічне посилання в даних користувача EC2 чи в цих метаданих, а Outputs показує кожному, хто читає стек.

Кожна така відмова називає параметри й не наводить жодного значення.

Вилучення ресурсів із запозиченого шаблону

Ресурси запозиченого шаблону належать йому самому: значення потрапляють до нього лише через параметри, які він оголошує, тому шаблон, отриманий із git-репозиторію, що оголошує ресурс, якого Release не повинен створювати, — бакет, який оператор уже надає, ключ, яким платформа керує деінде, — неможливо змінити значенням. Саме для цього призначені записи omits: у сутностях Recipe або FeatureRecipe. Цей провайдер враховує їх для запозиченого шаблону і більше ні для чого: фрагменти, які створює запис artifacts:, рендеряться без них.

spec:
capability: cloudformation
implements: core/store:1.0.0
source:
kind: git-repository
url: https://git.example.com/platform/templates.git
ref: v3.2.0
module_subdir: store
omits:
# The template bundles an access-log bucket; this Release logs elsewhere.
- kind: AWS::S3::Bucket
name: StoreLogs

Запис називає один ресурс за його Type і логічним ідентифікатором. Поле kind запису — це Type ресурсу, наприклад AWS::S3::Bucket, а його name — логічний ідентифікатор ресурсу, тобто його ключ у Resources; обидва порівнюються точно так, як написано, і обидва мають збігатися, тож запис, у якого Type правильний, а логічний ідентифікатор — ні, нічого не вилучає. Шаблон не має просторів імен, тому запис із namespace зупиняє збірку під час рендерингу компонента з зазначенням цього запису; кожен запис перевіряється до того, як щось буде вилучено.

Зіставляється кожен шаблон джерела. Однофайлове джерело має один шаблон. Джерело-каталог — а джерело, отримане з git-репозиторію, завжди є таким, — містить кожен файл, що закінчується на .yaml, .yml, .json або .template, і запис вилучає кожен названий ним ресурс у будь-якому з них; файл, що лежить поруч із шаблонами, ніколи не читається. Провайдер повідомляє, скільки ресурсів вилучив кожен запис у всіх них разом, а запис, що не вилучив жодного, зупиняє збірку; див. An omits entry left out nothing the source rendered (Запис omits не вилучив нічого з того, що відрендерило джерело).

Вилучений ресурс зникає раніше, ніж будь-що інше прочитає шаблон. Він не позначається походженням, не враховується серед імен, які містить стек, — тож інший компонент може додати ресурс із тим самим логічним ідентифікатором, і вони не зіткнуться, — і ніколи не потрапляє до зібраного стека. Усе інше в шаблоні записується точно так, як було б, якби шаблон створили без цього ресурсу, а шаблон, з якого вилучено всі ресурси, зберігає порожній розділ Resources.

На вилучений ресурс не повинно посилатися те, що залишилося, бо CloudFormation відхиляє шаблон, який називає неоголошений ним ресурс. Після видалення ресурсів кожне посилання на один із них, що лишається в решті шаблонів, зупиняє збірку, а повідомлення називає шаблон, ресурс, спосіб, яким посилання його називає, і місце посилання у вигляді шляху від кореня шаблону — наприклад, /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName. Посилання — це те, що довідник шаблонів CloudFormation визначає як називання ресурсу за його логічним ідентифікатором; воно читається в тілі кожного ресурсу — зокрема в його властивостях, метаданих і політиках — та в кожному виході:

  • Ref з логічним ідентифікатором як аргументом;
  • Fn::GetAtt як список, перший елемент якого — логічний ідентифікатор, або як один рядок — !GetAtt StoreLogs.Arn, — текст якого до першої крапки є ним;
  • DependsOn ресурсу як один логічний ідентифікатор або їх список;
  • кожна змінна Fn::Sub у рядковій і списковій формах: ${StoreLogs} і ${StoreLogs.Arn} обидві називають StoreLogs.

Деякі значення лише схожі на посилання і не читаються як такі. ${!StoreLogs} — це літеральний текст, а змінна, яку називає мапа спискової форми, є значенням цієї мапи. Condition ресурсу і перший аргумент Fn::If називають умову, Fn::FindInMap — відображення, Fn::ImportValue — експорт іншого стека, а Fn::GetAZs — регіон. Розділи Conditions, Mappings, Parameters і Rules не можуть називати ресурс, а власний розділ верхнього рівня Metadata шаблону — це інформація, яку CloudFormation зберігає, а не читає, тож жоден із них не перевіряється. Ref або Fn::GetAtt, логічний ідентифікатор яких сам записано як внутрішню функцію, дійсні лише з перетворенням AWS::LanguageExtensions, яке розв’язує їх під час розгортання стека (див. Розділи верхнього рівня в зібраному стеку), тож вони не називають ресурсу, який може прочитати перевірка, і залишаються як є; так само й посилання на ресурс, якого джерело ніколи не оголошувало.

Перевірка читає власні шаблони сутності Recipe або FeatureRecipe, що оголошує записи, разом. Вони збираються в один стек, тож посилання на логічний ідентифікатор, який досі оголошує інший із цих шаблонів, не зупиняється. Більше нічого не читається: посилання на вилучений ресурс зупиняє збірку, навіть якщо інший компонент оголошує ресурс із цим логічним ідентифікатором, а посилання, зроблене будь-чим іншим, що збирається в стек, — іншим компонентом, приєднаною сутністю Feature або власними записами artifacts: сутності Recipe, — ця перевірка не бачить, тож CloudFormation відхилить стек під час розгортання. Щоб зберегти посилання, збережіть ресурс. Значення, прив’язане до параметра, замінює лише посилання на цей параметр, тож посилання на ресурс належить самому шаблону і значенням його не змінити: вилучіть також ресурс, що робить це посилання, або видаліть запис. Вихід не є ресурсом, і жоден запис його не називає, тому ресурс, який називають Outputs шаблону, вилучити з нього неможливо: його вилучення зупиняє збірку.

Анотації хмарної цілі

Три анотації межі повідомляють провайдеру, куди розгортається стек, щоб він міг правильно зв’язати міжстекові посилання:

  • aggrega.ai/aws-account — обліковий запис AWS, у який розгортається стек.
  • aggrega.ai/aws-region — регіон AWS, у який розгортається стек.
  • aggrega.ai/aws-assume-role-arn — ARN ролі IAM, яку бере на себе міжакаунтне читання стека, щоб дістатися експортованих значень сусіднього стека.

Ці анотації непрозорі для компілятора — він передає їхні значення провайдеру, не інтерпретуючи їх (див. well-known-annotations.md). Їх задають на межі виробника — стека, якому належить експортоване значення. Міжакаунтне читання бере на себе роль в обліковому записі виробника, тож обліковий запис, регіон і роль, що описують читання, беруться з анотацій межі виробника, а не споживача.

Посилання в межах стека

Коли ребро uses з’єднує два компоненти, що потрапляють в ту саму межу — той самий стек, — спожите значення підключається як Fn::GetAtt до логічного ідентифікатора ресурсу-виробника в межах одного шаблону. Значення provides виробника надходить у відрендерені вхідні дані споживача як нативне посилання в межах стека; експорт чи імпорт не потрібні. Фрагмент споживача може записати таке значення без лапок — Value: {{ .context.inject.env.DB_HOST }} — або в лапках — Value: "{{ .context.inject.env.DB_HOST }}": в обох випадках шаблон читає !GetAtt Db.Endpoint.Address як вбудовану функцію, бо рядок, що є рівно однією короткою формою, потрапляє до стека як ця вбудована функція у фрагменті так само, як і у valuesMapping. Приклад aws-rds-and-ecs-service показує це на визначенні завдання Amazon ECS, яке зчитує адресу екземпляра RDS в одному стеку.

Зв’язування між стеками

Коли ребро uses перетинає межу з однієї межі в іншу — два компоненти збираються в різні стеки, — посилання не може бути простим значенням, бо створене значення не існує, доки стек виробника не розгорнуто. Провайдер зв’язує його як міжстекове посилання CloudFormation. Стек виробника публікує значення як Output стека з Export під детермінованим іменем експорту (виведеним із релізу, межі, компонента та наданого ключа). Стек споживача читає його однією з двох вбудованих функцій, яку вибирають, порівнюючи оголошене розміщення двох меж:

  • Fn::ImportValue — випадок того самого облікового запису й того самого регіону. CloudFormation розв’язує імпорт за відповідним іменем експорту в межах облікового запису та регіону.
  • Fn::GetStackOutput — справжнє читання між обліковими записами або між регіонами. Споживач читає вихід стека виробника напряму, перебираючи роль aws-assume-role-arn межі виробника в обліковому записі та регіоні виробника.

Семантика визначення. Провайдер вибирає Fn::GetStackOutput лише тоді, коли обидві кінцеві точки оголошують розміщення (обліковий запис/регіон) і ці розміщення відрізняються. У кожному іншому випадку — жодна не оголошує, оголошує лише одна або обидві оголошують однакове розміщення — він використовує Fn::ImportValue. Це консервативне правило: міжстекове читання в тому самому обліковому записі лишається простим імпортом, а вбудовану функцію прямого читання зарезервовано для справжнього переходу між обліковими записами або регіонами.

Стек виробника завжди публікує Export, навіть коли певний споживач читає його з іншого облікового запису через Fn::GetStackOutput. Невикористаний експорт нічого не робить, а безумовна публікація зберігає шаблон виробника незалежним від того, як кожен споживач вирішує читати значення.

Кілька споживачів одного значення читають один експорт. Коли більше ніж один компонент читає те саме надане значення через межу — два споживачі в одному стеку або споживачі в кількох стеках, — стек виробника публікує Export цього значення один раз, і кожен споживач читає одне ім’я: кожна Fn::ImportValue імпортує той самий експорт, а споживач, розміщений в іншому обліковому записі чи регіоні, читає той самий вихід через Fn::GetStackOutput. Споживач, який також читає значення, якого не читає жоден інший споживач, додає лише експорт цього значення.

Приклад aws-rds-and-ecs-service будує випадок того самого облікового запису: стек екземпляра RDS експортує кожен запис, який споживає ребро сервера, а стек сервера читає кожен із них через Fn::ImportValue.

Примітка щодо версії. Fn::GetStackOutput — це нативна вбудована функція CloudFormation. Посилання між обліковими записами, згенероване з нею, потребує інструментів CloudFormation, які розпізнають цю функцію. Шлях у тому самому обліковому записі використовує Fn::ImportValue, яка доступна повсюдно.

Значення, прочитане зі з’єднання, а не впроваджене

Сутність Recipe споживача може читати значення виробника безпосередньо зі з’єднання через .context.uses.<alias>.provides, замість того щоб отримувати їх через блок inject з’єднання. На межі стека таке читання підключається так само, як впроваджене значення:

  • Значення, що є вбудованою функцією CloudFormation, — тег короткої форми, наприклад !GetAtt Db.Endpoint.Address, або відображення Ref чи Fn:: у повній формі — вказує на те, що оголошує лише стек виробника, тож споживач отримує те саме посилання між стеками, що й для впровадженого значення: стек виробника публікує Export для цього ключа, а споживач читає його через Fn::ImportValue або через Fn::GetStackOutput, якщо дві межі оголошують різні розміщення.
  • Значення, що є простим текстом, — порт, протокол, назва бази даних — означає те саме в будь-якому стеку, тож споживач отримує саме значення, і експорт для нього не публікується. Воно потрапляє у формі, в якій його читає CloudFormation: значення, записане цілком, рендериться так, як без межі, а значення у формі числа, записане в лапках, потрапляє як число.

Чи є значення вбудованою функцією, вирішує цей провайдер, читаючи значення так само, як він читає власний блок provides виробника. Компілятор передає значення в тому вигляді, в якому його записала сутність Recipe виробника, і не тлумачить його.

Шаблон може лише копіювати таке значення. Він може записати значення цілком, усередині довшого рядка або передати його через функцію, яка залишає його без змін, як-от quote. Порівняння, розгалуження, довжина чи функція, що змінює значення, — eq, if, len, upper — вирішувалися б за чимось іншим, ніж значення, бо на такому з’єднанні шаблон отримує заглушку, яку провайдер замінює після збирання обох стеків. Натомість збірка зупиняється з назвою шаблону й кожного прочитаного ним значення, разом зі з’єднанням, з якого його прочитано, і компонентом на кожному кінці; розгалужуйтеся за власним значенням компонента-споживача. Те саме стосується injectMapping приєднаної сутності FeatureRecipe і сутності FeatureRecipe з областю межі, яка читає з’єднання межі. Значення, записане всередині довшого рядка, натрапляє також на власне обмеження провайдера: посилання між стеками може стояти лише як ціле значення, тож вбудована функція, записана всередині довшого рядка, зупиняє збірку, як і у випадку впровадженого значення.

Як будується ім’я експорту

Чотири частини з’єднуються подвійним дефісом, і кожну частину записують літерами, цифрами та дефісами, з яких складається ім’я експорту. Літера чи цифра переноситься як є, так само як і дефіс усередині частини — payments-db лишається payments-db. Будь-який інший символ записується як коротка екранована послідовність, що починається з -z: скісна риска як -zs, підкреслення як -zu, крапка як -zd. Частина без жодного значення записується як -ze. Ім’я стека будується так само з релізу та межі.

Отже, експорт, що публікує host з компонента db у межі, чий вихідний каталог під dist/ — це stack-a/cloudformation, релізу orders, виглядає так:

aggrega--orders--stack-a-zscloudformation--db--host

Зворотне читання однозначне, і в цьому суть, а не просто зручність: оскільки частина ніколи не містить двох дефісів поспіль і ніколи не закінчується дефісом, подвійні дефіси завжди є з’єднаннями. Тому два різні набори частин завжди дають два різні імена. payments-db і payments_db потрапляють у два окремі експорти, а не зводяться до одного, і дефіс на краю однієї частини не можна прочитати як належний сусідній.

Щодо чого ім’я експорту унікальне і де це закінчується

У межах однієї збірки ім’я експорту ідентифікує рівно один реліз, межу, компонент і наданий ключ — жодні два з них не зводяться до одного імені, тож збірка не може втратити одне експортоване значення за іншим.

CloudFormation додатково вимагає, щоб ім’я експорту було унікальним серед усього, що вже розгорнуто в обліковому записі та регіоні, куди потрапляє стек. Це властивість розгортання, а не збірки, і вона лежить поза межами досяжності будь-якого виведення під час збірки: компілятор не автентифікується в AWS, не надсилає до нього запитів і не може прочитати вихід іншої збірки, тож ніщо, обчислене заздалегідь, не може побачити, що там уже розгорнуто.

Через цю межу розрізнення переносить ідентичність релізу, що стоїть на початку кожного імені експорту та стека. Два розгортання, які спільно використовують обліковий запис і регіон, тримають свої експорти окремо завдяки випуску під різними іменами — це важіль, який у ваших руках, і причина, чому ідентичність релізу стоїть на початку імені, а не в кінці.

Запис Outputs може оголосити власне ім’я експорту

Блок Outputs: сутності Recipe — це написаний автором CloudFormation, і запис у ньому може мати власний Export: з Name:. Це ім’я потрапляє до зібраного стека точно так, як написано: provider не переписує його, не додає до нього префікс і не вимагає, щоб воно мало вигляд похідного.

Зазвичай більше про це сказати нічого. Написане автором ім’я експорту, яке не збігається з жодним ім’ям, що його виводить provider, публікується поряд із похідними й ніколи не викликає зауважень. Таке авторство підтримується; не підтримується лише один збіг.

Збірка зупиняється, коли написане автором ім’я експорту дорівнює імені, яке provider виводить для міжмежового зв’язку в тій самій збірці. Обидва оголошення потрапили б до зібраного шаблону, і одне ім’я експорту було б оголошено двічі в одному стеку, а ім’я експорту має бути унікальним, тож обидва не можуть існувати одночасно. Повідомлення про зупинку наводить похідне ім’я експорту й чотири частини, з яких його побудовано, щоб ви могли побачити, який зв’язок його створив, а також називає вихідне значення стека, під яким міститься авторське оголошення, позначене як ім’я, що його збирає provider, а не ім’я, написане в Recipe. Саме ім’я експорту слід шукати у ваших Recipes. Авторський запис містить його точно так, як і повідомлення про зупинку, — саме ця тотожність і робить їх колізією, — тож це єдиний рядок, що з’являється і в повідомленні, і у ваших власних файлах. Зупинку усуває перейменування імені експорту, яке оголошує цей запис, а також видалення блоку Export: цього запису, щоб міжстекове зв’язування саме опублікувало експорт.

Ця перевірка відбувається в межах збірки, а її область — один стек. Вона порівнює імена експортів, які оголошує зібраний стек, з іменами, що їх provider виводить для міжмежових зв’язків, які публікують у той самий стек, — це порівняння, яке збірка може виконати на основі того, що вона зібрала. Два стеки між собою не порівнюються. А те, з якими експортами, уже розгорнутими в обліковому записі та регіоні, зустрічається авторське ім’я, — це властивість розгортання, яка лежить поза межами досяжного для будь-якого виведення на етапі збірки, з причини, викладеної в розділі What an export name is unique against, and where that stops: компілятор не автентифікується в AWS, не надсилає до нього запитів і не може прочитати вихідні дані іншої збірки. Ім’я експорту, записане як intrinsic-функція, а не як звичайний рядок, лежить по той бік тієї самої межі: воно розв’язується під час розгортання, а тут ніщо не обчислює intrinsic-функції, тож збірці немає з яким ім’ям порівнювати.

Збірка також зупиняється, коли вихідне значення, у якому публікує міжмежовий зв’язок, уже має Export, якого зв’язок не писав. Це вихідне значення provider збирає для наданого ключа, який читає споживач, тож Recipe, чий блок Outputs: записує запис під тим самим ключем із власним Export:, розміщує свій експорт саме там, де має бути експорт зв’язку. Якщо ім’я цього експорту не збігається точно з тим, що виводить provider, — а в такому разі це власний експорт зв’язку, і його імпортує кожен споживач, — обидва не можуть там існувати: запис експорту зв’язку перезаписав би ваш, а збереження вашого залишило б кожного споживача з імпортом імені, якого зв’язок не публікував. Повідомлення про зупинку наводить похідне ім’я експорту й чотири частини, з яких його побудовано, і повідомляє, що знайдено в цьому вихідному значенні: ім’я експорту, яке оголошує запис, ім’я, записане як intrinsic-функція, блок Export:, що нічого не називає, або Export:, записаний як звичайне значення, а не як блок. Зупинку усуває видалення блоку Export: цього запису, і тоді міжстекове зв’язування публікує експорт, який імпортує кожен споживач.

Порядок розгортання

Значення syncWave: межі сутності Release визначає порядок створення стека, у який збирається ця межа. Кожен компонент у межі успадковує хвилю межі, а там, де кілька меж зводяться до одного вихідного каталогу — тож їхні фрагменти збираються в один шаблон, — стек містить більше ніж одну хвилю, і провайдер виражає порядок між ними через DependsOn.

Кожен ресурс називає всі ресурси безпосередньо попередньої хвилі, що має хоч якісь ресурси, і жодної ранішої хвилі. Решту ланцюжка вибудовує CloudFormation: ресурс у хвилі 2 залежить від хвилі 1, яка залежить від хвилі 0, тож уся послідовність упорядкована, а власний список кожного ресурсу лишається розміром з одну хвилю, а не з увесь стек. Хвилі не мусять іти поспіль, а від’ємні значення цілком звичайні — -1 часто обирають для бакета чи ролі, які читає решта стека. Найнижча хвиля не називає нічого, бо їй ніщо не передує.

Що це за порядок: порядок створення, а у зворотному напрямку — порядок видалення. CloudFormation обробляє ресурси паралельно, наскільки може, а DependsOn скасовує цю паралельність, щоб обробляти названі ресурси у визначеному порядку. Атрибут керує обома напрямками, тож хвиля, яка створює ресурс раніше, також видаляє його пізніше — правильна послідовність демонтажу приходить разом із порядком і не потребує нічого іншого.

Це не порядок готовності. Шаблон стека не виражає поняття придатності ресурсу до роботи, тож ніщо тут не чекає, доки ресурс стане готовим, — лише доки CloudFormation завершить його створення. Це суттєва відмінність від тієї самої хвилі в compose, де на сервіс, який оголошує healthcheck, чекають, доки він не повідомить про справний стан: compose має примітив готовності, на який можна спертися, а шаблон стека — ні. Ця ціль пропонує порядок створення, і чітко сказати про це корисніше, ніж додавати застереження до обіцянки, яку вона не може дати.

Написаний автором DependsOn доповнюється, а не замінюється. Фрагмент, що оголошує власне обмеження порядку, зберігає його: записи, які він написав, ідуть першими, у тому порядку, в якому він їх написав, а за ними йдуть записи хвилі. Обидві вимоги виконуються, і жодна не приховує іншу. Читається як окремий логічний ID, так і список, а об’єднане значення виводиться як список — єдиний запис, придатний за будь-якої кількості записів, яку дає об’єднання.

Стек, усі ресурси якого мають одну хвилю, нічого від цього не отримує. Так само й сутність Release, яка взагалі не оголошує syncWave: кожен учасник має типове значення поля 0, зібраний шаблон містить одну хвилю, і результат точно такий, яким він був би, якби провайдер не виражав порядку хвиль.

Порядок між двома стеками не виражається і не наближається. DependsOn називає ресурс у тому самому шаблоні, а компоненти, що збираються в інший стек, лежать поза ним. Тож хвиля впорядковує кожен ресурс у стеку, в який вона збирається, і нічого поза ним. Послідовність двох стеків — справа оператора, так само як міжстекове посилання розв’язується під час розгортання, а не під час збирання.

Порядок, який хвилі не виражають, лишається справою самого CloudFormation, і посилання між ресурсами вже несуть значну його частину: Fn::GetAtt на ресурс-виробник вказує CloudFormation створити цей ресурс першим. Фрагмент, якому потрібне обмеження, що не випливає ні з посилань, ні з хвиль, сам пише DependsOn — саме цей випадок і зберігає описане вище об’єднання.

Детермінованість

За однакових вхідних даних провайдер між запусками видає побайтово ідентичний шаблон стека: логічні ідентифікатори, ключі виходів, імена експортів і порядок ресурсів детерміновані, тож diff шаблону стека CloudFormation чистий під час рев’ю в GitOps.