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

CloudFormation Provider

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

Рецепты-фрагменты, собранные в стек

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

  • Входные данные-фрагменты (artifacts). Recipe описывает фрагменты ресурсов напрямую; провайдер нормализует их к чистому JSON с внутренними функциями в полной форме и объединяет их в собранном стеке.
  • Входные данные из источника. Recipe ссылается на существующий шаблон CloudFormation (YAML или JSON); провайдер нормализует его к JSON в полной форме и проверяет его структуру перед сборкой, заполняет параметры, объявленные шаблоном, из valuesMapping сущности Recipe — см. Значения параметров шаблона из источника, — и исключает все ресурсы, названные в записях omits: сущности Recipe, — см. Исключение ресурсов из шаблона из источника.

Собранный шаблон — чистый JSON. Внутренние функции выводятся дословно и никогда не вычисляются во время сборки: компилятор не может разрешить значение, которое существует только после развёртывания стека, а вычисление такого значения нарушило бы контракт ahead-of-time-компиляции.

Feature, присоединённая к компоненту, вносит вклад в тот же стек

Feature, присоединённая к компоненту, вносит свои ресурсы в стек, в который собирается её компонент-хост, на тех же условиях, что и собственный Recipe компонента-хоста. Отдельного шаблона рядом с ним нет: собранный стек — это всё, что этот провайдер выводит для выходного каталога, поэтому ресурсы присоединённой сущности Feature либо находятся в этом стеке, либо не развёртываются вовсе. Отсоединение сущности Feature удаляет ровно эти ресурсы и не затрагивает собственные ресурсы компонента-хоста.

Поскольку они попадают в собранный стек, они разделяют его имена. Логические идентификаторы ресурсов присоединённой сущности Feature находятся в том же пространстве, что и идентификаторы компонента-хоста и всех других Features, присоединённых рядом с ней, поэтому раздел Имена в собранном стеке применяется к ним без изменений. Если два участника сходятся на одном имени, остановка называет компонент и ключ, под которым присоединена Feature, так что оба конца коллизии можно найти в ваших собственных файлах.

Выходные значения присоединённой сущности Feature публикуются под именем её компонента-хоста, а логические идентификаторы её ресурсов — нет. Две половины стека именуются по разным правилам, поэтому отвечают на этот вопрос по-разному. Логический идентификатор ресурса выводится ровно так, как его описал 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 именуют свои записи логическим ID. Поскольку провайдер переносит имя ровно так, как вы его написали, алфавит, допускаемый логическим ID, распространяется и на эти разделы: имя в одном из этих четырёх разделов, содержащее что-либо кроме букв и цифр, останавливает сборку — см. 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 при развёртывании стека, которое сборка не может прочитать.
макрос, определённый вашей учётной записьюпереносится для стека только с одним компонентом. Рядом с любым другим сборка останавливается, потому что сборке неизвестно, что он делает с остальным шаблоном.

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

Имена в собранном стеке

Логический ID в CloudFormation уникален в пределах одного шаблона и допускает только буквы и цифры, а все компоненты, собираемые в этот шаблон, разделяют его имена — включая компоненты из второй границы, когда обе разрешаются в один и тот же выходной каталог. Поэтому каждое имя, по которому стек к чему-либо обращается, должно быть уникальным среди всех компонентов, внёсших его, и набор участников не всегда ограничен одной границей.

Логические ID ресурсов берутся из Recipe. Провайдер выводит их ровно так, как они написаны, и ни один не переписывает, поэтому имя, которое вы видите в собранном шаблоне, — это имя, которое написал Recipe. Recipes CloudFormation из стандартной библиотеки выводят его из собственного имени экземпляра компонента, считая разделители этого имени границами слов: экземпляр payments-db называет свой ресурс PaymentsDb. Поэтому два экземпляра одного типа описывают два ресурса, а не соперничают за один.

Имена выходных значений ограничены областью публикующего компонента. Каждая запись provides появляется как выходное значение, названное по публикующему компоненту и записи вместе — компонент payments-db, публикующий host, появляется как paymentsXzhdbXXhost, — поэтому два компонента, публикующие одну и ту же запись, приходят к двум отдельным выходным значениям, и смысл выходного значения не меняется, когда в стек добавляется другой компонент. Потребитель из другого стека в той же учётной записи и регионе импортирует по имени экспорта, а не по этому имени, поэтому имя экспорта не затрагивается; чтение из другой учётной записи или другого региона указывает это выходное значение — провайдер записывает его за вас (см. Межстековое связывание).

Как строится имя выходного значения

Логический ID не допускает символов-разделителей, поэтому имя, построенное из написанного вами, должно как-то перенести ваши разделители. Отбрасывать их означало бы терять информацию: 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

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

Для логических ID ресурсов действует другое правило, потому что их строит не провайдер: он выводит то, что написал Recipe. Recipes CloudFormation из стандартной библиотеки выводят ID, считая разделители имени экземпляра границами слов — экземпляр payments-db называет свой ресурс PaymentsDb, — и такое выведение отбрасывает разделители, поэтому два имени экземпляров, различающиеся только пунктуацией или только регистром буквы, всё равно дают одно имя ресурса. Сборка останавливается, называя каждый экземпляр, пришедший к этому имени, и само имя, вместо того чтобы вывести один ресурс там, где были объявлены два компонента. Называются все, а не некоторые, потому что в коллизии ничто не делает выведение одного экземпляра задуманным. Переименование всех, кроме одного, устраняет проблему.

Логический ID ресурса вне алфавита останавливает сборку

Уникальность и алфавит — два отдельных требования, и набор имён может удовлетворять первому и нарушать второе. Поскольку провайдер выводит логический ID ресурса ровно так, как его написал Recipe, ID, который создаёт Recipe, должен быть таким, какой шаблон CloudFormation может содержать сам по себе: буквы и цифры, и ничего больше.

Здесь пути выведенного и переданного как есть имени расходятся. Имя выходного значения строит провайдер, кодируя публикующий компонент и запись, поэтому оно лежит внутри алфавита, как бы вы ни написали любую из половин. Логический ID ресурса передаётся как есть, поэтому шаблон получает то, что написал Recipe.

Это становится ограничением и на имена компонентов, когда Recipe записывает имя экземпляра компонента прямо в логический ID. Имя компонента может содержать дефис или подчёркивание; логический ID — нет. Поэтому компонент, который вы нацеливаете на этот провайдер через такой Recipe, называется только буквами и цифрами — paymentsdb, а не payments-db, — а всё остальное останавливает сборку.

Остановка называет участника, чей Recipe создал ID, сам ID и каждый недопустимый в нём символ, а также сообщает, что можно написать вместо этого. Устранить её можно двумя способами, и первый доступен вам всегда:

  • Пусть Recipe создаёт собственный логический ID, а не передаёт имя напрямую. Так поступают Recipes CloudFormation из стандартной библиотеки — они считают разделители имени экземпляра границами слов, поэтому экземпляр payments-db называет свой ресурс PaymentsDb, и вы сохраняете выбранное имя компонента. Выведение ID таким способом меняет эту остановку на правило коллизий выше: два имени экземпляров, различающиеся только пунктуацией, дают одно имя ресурса.
  • Если Recipe всё же передаёт имя напрямую, переименуйте передаваемое так, чтобы оно состояло только из букв и цифр. Для собственного Recipe компонента это имя компонента. Feature, присоединённая к компоненту, называет свои ресурсы из собственного FeatureRecipe, поэтому переименование компонента-хоста на них не влияет — изменить нужно ID, который пишет этот Recipe.

Провайдер отказывает; он не исправляет молча. Переписать ID за вас казалось бы полезным, но это не так. Логический ID — это то, по чему CloudFormation идентифицирует ресурс между обновлениями, поэтому его изменение — не переименование, а обращение к другому ресурсу. Подставленный провайдером ID указывал бы не на ресурс, уже развёрнутый под написанным вами ID, а подстановку вы не запрашивали и обнаружили бы её только в выведенном шаблоне. Остановленная сборка называет проблему, пока её ещё можете исправить вы.

Переносимое имя раздела вне алфавита останавливает сборку

Логические идентификаторы ресурсов — не единственные имена, которые провайдер переносит точно так, как вы их написали. 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 проходит структурную проверку перед рендерингом: провайдер разбирает шаблон и нормализует его встроенные функции, а если шаблон некорректен, останавливает сборку с понятным сообщением, в котором назван проблемный узел. Разбор проверяет форму, а не семантику: он не обращается к 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. Так опубликованная ссылка другого компонента попадает в параметр: CloudFormation-сущности Recipes каталога публикуют такую ссылку как текст в краткой форме, а 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 и логическому ID. Поле kind записи — это Type ресурса, например AWS::S3::Bucket, а её name — логический ID ресурса, его ключ в Resources; оба сравниваются точно так, как написаны, и оба должны совпасть, поэтому запись с верным Type и неверным логическим ID ничего не исключает. В шаблоне нет пространств имён, поэтому запись с namespace останавливает сборку при рендеринге компонента, и сообщение называет эту запись; все записи проверяются до того, как что-либо будет исключено.

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

Исключённый ресурс удаляется до того, как что-либо ещё прочитает шаблон. Он не получает отметки о происхождении, не учитывается среди имён, которые несёт стек, — поэтому другой компонент может добавить ресурс с тем же логическим ID, и они не столкнутся, — и никогда не попадает в собранный стек. Всё остальное в шаблоне записывается точно так, как если бы шаблон был написан без этого ресурса, а шаблон, из которого исключены все ресурсы, сохраняет пустой раздел Resources.

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

  • Ref с логическим ID в качестве аргумента;
  • Fn::GetAtt в виде списка, первый элемент которого — логический ID, или в виде одной строки — !GetAtt StoreLogs.Arn, — текст которой до первой точки является логическим ID;
  • DependsOn ресурса — один логический ID или их список;
  • каждая переменная 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, логический ID которых сам записан встроенной функцией, допустимы только с преобразованием AWS::LanguageExtensions, которое вычисляет его при развёртывании стека (см. Разделы верхнего уровня в собранном стеке), поэтому такая ссылка не называет ресурс, который может прочитать проверка, и остаётся как есть; так же обстоит дело со ссылкой на ресурс, который источник никогда не объявлял.

Проверка читает собственные шаблоны объявляющей сущности Recipe или FeatureRecipe вместе. Они собираются в один стек, поэтому ссылка на логический ID, который ещё объявляет другой из этих шаблонов, сборку не останавливает. Больше ничего не читается: ссылка на исключённый ресурс останавливает сборку, даже если другой компонент объявляет ресурс с этим логическим ID, а ссылку, сделанную чем-либо ещё, что собирается в стек, — другим компонентом, присоединённой сущностью 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 по логическому ID ресурса-производителя в пределах одного шаблона. Значение 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 пересекает границу между двумя boundary — два компонента собираются в разные стеки, — ссылка не может быть простым значением, потому что производимое значение не существует, пока не развёрнут стек-производитель. Провайдер связывает их через межстековую ссылку CloudFormation. Стек-производитель публикует значение как Output стека с Export под детерминированным именем экспорта (выводимым из релиза, boundary, компонента и предоставляемого ключа). Стек-потребитель читает его одной из двух встроенных функций, выбираемой сравнением объявленного размещения двух boundary:

  • Fn::ImportValue — случай одного аккаунта и одного региона. CloudFormation разрешает импорт по совпадающему имени экспорта в пределах аккаунта и региона.
  • Fn::GetStackOutput — настоящее чтение между аккаунтами или регионами. Потребитель читает вывод стека-производителя напрямую, принимая роль aws-assume-role-arn boundary производителя в аккаунте и регионе производителя.

Семантика определения. Провайдер выбирает 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. Любой другой символ записывается короткой escape-последовательностью, начинающейся с -z: косая черта — -zs, подчёркивание — -zu, точка — -zd. Часть без значения записывается как -ze. Имя стека строится так же из релиза и boundary.

Таким образом, экспорт, публикующий host из компонента db в boundary, чей выходной каталог внутри dist/ — stack-a/cloudformation, релиза orders, выглядит так:

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

Обратное чтение однозначно, и это суть, а не любезность: поскольку часть никогда не содержит два дефиса подряд и никогда не заканчивается дефисом, двойные дефисы — всегда соединения. Поэтому два разных набора частей всегда дают два разных имени. payments-db и payments_db приводят к двум отдельным экспортам, а не сходятся в одном, и дефис на краю одной части нельзя прочитать как принадлежащий соседней.

Относительно чего уникально имя экспорта и где это заканчивается

В пределах одной сборки имя экспорта идентифицирует ровно один релиз, boundary, компонент и предоставляемый ключ — никакие два из них не сходятся в одном имени, поэтому сборка не может потерять одно экспортируемое значение за другим.

CloudFormation дополнительно требует, чтобы имя экспорта было уникальным среди всего, что уже развёрнуто в аккаунте и регионе, куда попадает стек. Это свойство развёртывания, а не сборки, и оно лежит за пределами того, что может охватить любое вычисление во время сборки: компилятор не аутентифицируется в AWS, не запрашивает его и не может читать результат другой сборки, поэтому ничто вычисленное заранее не может увидеть, что там уже развёрнуто.

Различие через эту границу переносит идентичность релиза, стоящая в начале каждого имени экспорта и стека. Два развёртывания в одном аккаунте и регионе разделяют свои экспорты, выпускаясь под разными именами, — это рычаг, который находится в ваших руках, и причина, по которой идентичность релиза стоит в начале имени, а не в конце.

Запись Outputs может объявить собственное имя экспорта

Блок Outputs: в сущности Recipe — это написанный автором CloudFormation, и запись в нём может содержать собственный Export: с Name:. Это имя попадает в собранный стек ровно в том виде, в каком написано: провайдер не переписывает его, не добавляет к нему префикс и не требует, чтобы оно выглядело как производное.

Обычно больше сказать об этом нечего. Заданное автором имя экспорта, не совпадающее ни с одним именем, которое выводит провайдер, публикуется наряду с производными и никак не отмечается. Такое авторство поддерживается; не поддерживается только одно совпадение.

Сборка останавливается, когда заданное автором имя экспорта совпадает с именем, которое провайдер выводит для межграничной связи в той же сборке. Оба объявления попали бы в собранный шаблон, и одно имя экспорта оказалось бы объявлено в одном стеке дважды, а имя экспорта должно быть уникальным, поэтому оба объявления сосуществовать не могут. Сообщение об остановке приводит производное имя экспорта и четыре части, из которых оно построено, чтобы можно было увидеть, какая связь его породила, и называет выход стека, под которым находится авторское объявление, помечая его как имя, собираемое провайдером, а не написанное в сущности Recipe. Именно имя экспорта следует искать в ваших Recipes. Авторская запись пишет его точно так же, как сообщение об остановке, — именно это тождество и делает их коллизией, — поэтому это единственная строка, которая встречается и в сообщении, и в ваших собственных файлах. Остановку устраняет переименование имени экспорта, которое объявляет эта запись, а также удаление блока Export: этой записи, после чего экспорт публикует сама межстековая связь.

Проверка выполняется в рамках сборки, и её область — один стек. Она сравнивает имена экспортов, которые объявляет собранный стек, с именами, которые провайдер выводит для межграничных связей, публикующих в тот же стек, — это сравнение сборка может сделать на основе того, что она собрала. Два стека между собой не сравниваются. А то, с чем авторское имя встретится среди экспортов, уже развёрнутых в учётной записи и регионе, — это свойство развёртывания, лежащее за пределами досягаемости любого вывода на этапе сборки, по причине, изложенной в разделе Относительно чего имя экспорта уникально и где это заканчивается: компилятор не проходит аутентификацию в AWS, не обращается к нему и не может прочитать результат другой сборки. Имя экспорта, записанное как встроенная функция, а не как обычная строка, находится по ту же сторону этой границы: оно разрешается во время развёртывания, а здесь встроенные функции не вычисляются, так что сборке нечего сравнивать.

Сборка также останавливается, когда выход, в который публикует межграничная связь, уже содержит Export, написанный не этой связью. Этот выход провайдер собирает для предоставляемого ключа, который читает потребитель, поэтому Recipe, блок Outputs: которой пишет запись под тем же ключом с собственным Export:, помещает свой экспорт ровно туда, куда идёт экспорт связи. Если только имя этого экспорта не совпадает в точности с именем, которое выводит провайдер, — тогда это собственный экспорт связи и его импортирует каждый потребитель, — оба не могут там находиться: запись экспорта связи перезаписала бы ваш, а сохранение вашего оставило бы каждого потребителя импортирующим имя, которое связь не публиковала. Сообщение об остановке приводит производное имя экспорта и четыре части, из которых оно построено, и сообщает, что найдено в этом выходе: имя экспорта, объявленное записью, имя, записанное как встроенная функция, блок 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 — именно этот случай сохраняет описанное выше слияние.

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

При одних и тех же входных данных провайдер от запуска к запуску выдаёт побайтно идентичный шаблон стека: логические ID, ключи выходных значений, имена экспортов и порядок ресурсов детерминированы, поэтому шаблон стека CloudFormation даёт чистый diff при ревью в GitOps.