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

Terraform Provider

Провайдер terraform преобразует сущности Aggrega Recipes в конфигурацию Terraform. Он генерирует конфигурацию и никогда не запускает Terraform: сборка Aggrega — это компиляция ahead-of-time (заранее), поэтому она не может разрешить идентификаторы ресурсов, IP-адреса и выходные значения, которые существуют только после terraform apply. Интерполяции Terraform ${ ... } проходят без изменений как детерминированные строки-указатели, которые среда выполнения Terraform разрешает позже. Провайдер работает офлайн и герметично — он никогда не обращается к сети и никогда не вызывает terraform или tofu.

Как устроена граница

Провайдер terraform компонует границу, а не выпускает её компоненты рядом друг с другом. Каждая граница, которую он рендерит, получает одну корневую конфигурацию, aggrega.modules.tf, в которой каждый отрендеренный в ней компонент объявлен как блок module, чей source — собственный подкаталог этого компонента в modules/:

module "cache" {
source = "./modules/cache"
}
module "db" {
source = "./modules/db"
allocated_storage = 100
db_name = "appdb"
engine_version = "11.4"
}

Собственные файлы каждого компонента — вендоренный модуль или написанное тело, а также отметка о происхождении — лежат в подкаталоге, на который указывает его блок. Это стандартная для Terraform структура «корень компонует дочерние модули», соглашение которой состоит в том, что вложенные модули находятся в подкаталоге modules/, и такую раскладку получает каждая граница terraform, содержит ли она один компонент или несколько. Сущность Feature, прикреплённая к компоненту или к границе, объявляется отдельным блоком module в той же корневой конфигурации — см. Куда попадает вывод прикреплённой сущности Feature.

Эта форма несёт нагрузку, а не является косметической, по двум причинам.

Граф зависимостей Terraform строится для каждой конфигурации отдельно. Components, выведенные в разные каталоги, образуют отдельные графы, никак не связанные между собой: ни ссылка, ни depends_on не может дотянуться из одного в другой, и ни один terraform plan не видит их оба. Один корень, включающий каждый компонент как дочерний модуль, помещает всю границу в один граф и один план.

Файлы компонента адресуются его собственным каталогом. Два компонента одной границы могут вендорить модули, которые пишут файлы с одинаковыми именами — main.tf, variables.tf, — и каждый набор лежит в каталоге своего компонента, а не претендует на один путь.

Где настраивается провайдер

Конфигурация провайдера — блок provider — пишется в корне, никогда внутри модуля компонента. Документация Terraform гласит, что модуль, предназначенный для вызова из другого модуля, не должен содержать блоков provider, а вызываемый модуль наследует конфигурацию по умолчанию корня для каждого провайдера, который этот модуль использует. Модуль с собственным блоком provider нельзя вызвать с depends_on, count или for_each, а этот провайдер пишет depends_on в блоке module компонента всякий раз, когда другой компонент того же корня имеет более ранний syncWave, как описано ниже в разделе об упорядочении развёртывания; тогда Terraform отвергает всю конфигурацию при её загрузке, ещё до какого-либо планирования.

Поэтому Recipe, чей провайдер требует настройки, записывает эту конфигурацию как файл в spec.boundary.artifacts. Каждый такой файл записывается один раз рядом с aggrega.modules.tf, где Terraform читает его вместе с корневой конфигурацией, а модуль компонента сохраняет только своё объявление required_providers с источником и версией провайдера:

infra/terraform/
aggrega.modules.tf
provider-azurerm.tf
modules/
gateway/main.tf

Components одного корня, объявляющие один и тот же файл с одинаковым содержимым, используют одну общую копию; то же имя с другим содержимым останавливает сборку. Ресурсы модулей записываются относительно этой единственной конфигурации, поэтому именно с ней Terraform их и уничтожает. Release, удаляющий последний компонент, объявляющий этот файл, удаляет вместе с ним и файл, и тогда Terraform отказывается планировать уничтожение того, что создали эти модули, требуя блок provider, настраивающий провайдер. Уничтожьте эти ресурсы до удаления последнего такого компонента.

Где задаются входные данные компонента

Входные данные компонента — это аргументы его блока module в корневой конфигурации, и только там они записываются. Блок несёт аргументы, когда входные данные модуля задаёт компилятор, — у Recipe, вендорящего модуль через source:. Он пуст, когда Recipe сам написал тело конфигурации и разрешил свои значения в этом теле, так что компилятору передавать нечего.

Аргумент модуля — это позиция, которую вычисляет Terraform, поэтому значения попадают именно туда. Указатель ${ ... }, заданный Recipe, разрешается там, а не приходит в модуль как литеральная строка. Разрешается он относительно корневой конфигурации: ссылка называет что-то, что объявляет эта конфигурация, — один из её блоков module, в виде module.<name>.<output>, — а ссылка на что-либо необъявленное даёт явную ошибку во время планирования с указанием отсутствующего объекта.

Поэтому собственный каталог компонента — не та конфигурация, которую можно спланировать так, как она развёртывается. Его входные данные заданы уровнем выше, в корне, поэтому запуск движка из modules/<component> планирует нечто иное, и какой из двух исходов наступит, зависит от собственных блоков variable модуля:

  • Если хотя бы один вход не объявляет default, план явно завершается ошибкой — No value for required variable (Нет значения для обязательной переменной), с указанием каждой незаданной переменной и её строки и с предложением собственного средства Terraform -var / -var-file.
  • Если каждый вход имеет default, план выполняется успешно и строится из значений модуля по умолчанию, а не из значений, заданных корневой конфигурацией. Никаких предупреждений нет, поэтому именно этот случай важно знать: план, который выглядит правильным, описывает конфигурацию, которую никто не запрашивал.

Вместо этого планируйте собственный выходной каталог границы — тот, где лежит aggrega.modules.tf, непосредственно над modules/. Именно там находятся значения развёртывания, и это единственное место, где один план видит всю границу.

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

Компонент, связанный с другим ребром uses, читает опубликованные значения того компонента через собственный конвейер .context.inject (или через .context.uses.<alias>.provides.<name>). То, что он читает, — строка, которую компилятор передаёт без интерпретации, а место, куда она попадает, — это текст, который Terraform вычисляет в области видимости, куда его записал Recipe. У границы terraform две такие области, и лишь одна из них объявляет вызовы модулей, нужные для межкомпонентной ссылки:

  • корневая конфигурация объявляет каждого участника как блок module, поэтому module.<name>.<output> там разрешается;
  • собственный каталог компонента вообще не объявляет вызовов модулей, поэтому module.<name>.<output> там ничего не называет — каким бы ни был <name>. Подстановка правильного имени ничего не меняет, потому что отсутствует объявление, а не написание.

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

Пишите потребляющий Recipe как Recipe с source:. Его valuesMapping: становится аргументами его собственного блока module в корневой конфигурации — единственной позиции, которая и вычисляется, и находится в области видимости, где объявлены его соседи.

Разобранная пара

Производитель публикует адрес, называющий его собственный вызов модуля, — именно эту форму объявляет область видимости потребителя. .context.instance_id доступен при вычислении provides, и для компонента, объявленного в сущности Aggregate развёртывания, это имя, которое носит блок module этого компонента:

# Recipe — the producer. Its vendored module declares `output "endpoint"`.
spec:
capability: terraform
implements: example/storage/object-store:1.0.0
source: ./module
valuesMapping: |
bucket: "{{ .values.bucket }}"
provides:
endpoint: "${module.{{ .context.instance_id }}.endpoint}"

Потребитель вендорит модуль, объявляющий вход, и отображает на него внедрённое значение:

# Recipe — the consumer. Its vendored module declares `variable "store_endpoint"`.
spec:
capability: terraform
implements: example/compute/reporting-api:1.0.0
source: ./module
valuesMapping: |
store_endpoint: "{{ .context.inject.env.STORE_ENDPOINT }}"

Сущность Aggregate связывает их, называя опубликованный ключ, который несёт ребро:

spec:
components:
store:
type: example/storage/object-store
values:
bucket: app-artifacts
api:
type: example/compute/reporting-api
uses:
store:
store:
target: store
inject:
env:
- in: STORE_ENDPOINT
from: endpoint

Сборка выпускает одну корневую конфигурацию, в которой ссылка и её объект объявлены вместе:

module "api" {
source = "./modules/api"
store_endpoint = "${module.store.endpoint}"
}
module "store" {
source = "./modules/store"
bucket = "app-artifacts"
}

Terraform разрешает module.store.endpoint, потому что та же конфигурация объявляет module "store", и значение доходит до модуля потребителя как обычный вход.

Пример aws-rds-and-ecs-service строит эту пару из сущностей Recipes стандартной библиотеки: база данных PostgreSQL, подготовленная опубликованным модулем RDS, и сервер, запущенный в Amazon ECS, чей аргумент environment содержит ${module.db.db_instance_address} в корневой конфигурации, объявляющей module "db".

Три способа ошибиться и как выглядит каждый из них

Recipe, который сам пишет своё тело, не может потреблять ссылку между компонентами. Recipe с artifacts: разрешает свои значения в тело, которое он пишет, и это тело выводится в собственный каталог компонента. Ссылка тогда оказывается в области видимости, где не объявлено ни одного вызова модуля:

Error: Reference to undeclared module
on modules/api/main.tf line 11, in output "seen":
11: value = "${module.store.endpoint}"
No module call named "store" is declared in module.api.

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

Адрес, указывающий на что-то внутри собственного модуля производителя, разрешается относительно корня, а не этого модуля. Запись provides, содержащая aws_db_instance.this.endpoint, указывает на ресурс, объявленный модулем производителя; записанная как интерполяция, она вычисляется там, где находится аргумент потребителя, то есть в корне:

Error: Reference to undeclared resource
on aggrega.modules.tf line 19, in module "api":
19: store_endpoint = "${aws_db_instance.this.endpoint}"
There is no managed resource "aws_db_instance" "this" definition in the root module.

Публикуйте ${module.<...>.<output>} и добавьте в модуль блок output для значения, вместо того чтобы обращаться к его ресурсам.

Запись provides без интерполяции доставляется как текст. Это единственный случай, который не приводит к ошибке: компилятор передаёт строки и не может отличить указатель от литерала, поэтому aws_db_instance.this.endpoint, записанный без ${ ... }, выводится как строка в кавычках, сборка проходит успешно, движок проходит валидацию, а потребитель получает символы aws_db_instance.this.endpoint. Пишите обёртку ${ ... } всякий раз, когда значение задумано как ссылка, — именно она помечает строку как то, что должен вычислить Terraform.

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

.context.instance_id задаёт идентичность компонента, а имя блока module выводится из каталога, в котором лежат файлы компонента. Для компонента, объявленного собственной сущностью Aggregate развёртывания, это одно и то же имя. Для компонента, включённого из другой сущности Aggregate, это не так: составная идентичность и имя модуля записываются в свои два алфавита по-разному, и ссылка тогда явно завершается ошибкой в корне, а не незаметно:

Error: Reference to undeclared module
on aggrega.modules.tf line 25, in module "api":
25: store_endpoint = "${module.nested-zdinner.endpoint}"
No module call named "nested-zdinner" is declared in the root module.

Объявляйте производителя, адрес которого разрешает другой компонент, в собственной сущности Aggregate развёртывания, рядом с компонентом, который его потребляет.

Куда попадает вывод подключённой сущности Feature

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

Каталог модуля подключения находится рядом с каталогом компонента, на один уровень ниже modules/, и назван по двум вещам, которые его идентифицируют, — компоненту, в котором оно размещено, и имени, под которым оно подключено, соединённым через --. Так, для компонента api с подключением aux корневая конфигурация объявляет два модуля:

module "api--aux" {
source = "./modules/api--aux"
}
module "api" {
source = "./modules/api"
}

У сущности Feature, подключённой на уровне границы, а не компонента, нет компонента-хоста, по которому её можно назвать, поэтому её каталог — это только её собственное имя: подключение aux на границе, содержащей компонент api, даёт ./modules/aux рядом с ./modules/api.

Почему рядом, а не внутри. Terraform объединяет все файлы верхнего уровня в каталоге модуля в одно пространство имён — output, variable, resource и locals одинаково, — поэтому два участника, разделяющие каталог, конфликтуют по любому имени, которое объявляют оба, как бы ни назывались их файлы. Разделяет их именно отдельный каталог для каждого. Размещение рядом, а не внутри — это также то, чего требуют собственные рекомендации Terraform для вложенных модулей: чтобы их компоновал вызывающий, а не они вызывали друг друга напрямую, создавая глубоко вложенное дерево модулей.

Соединение экранируется для каждой координаты. Каждая из двух координат записывается в алфавит каталогов до соединения, поэтому координату, которая сама содержит --, нельзя спутать с соединением: хост a--b с подключением c отличим от хоста a с подключением b--c. Латинские буквы ASCII в обоих регистрах, цифры, точка и подчёркивание проходят как написаны; написанный вами дефис сохраняется, если следующий за ним символ — один из них; всё остальное экранируется. Те же правило и алфавит формируют дочерние каталоги цели chart, поэтому каталог одного подключения пишется одинаково, какая бы из двух целей его ни выводила.

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

Из того, что подключение является отдельным модулем, следуют три вещи.

Его входные параметры задаются его собственным отображением. Для подключения, сущность FeatureRecipe которого подключает модуль и объявляет valuesMapping, значения, которые даёт это отображение, записываются как аргументы его собственного блока module — так же, как подключаемый модуль компонента получает свои значения. Сущность FeatureRecipe без valuesMapping не передаёт своему модулю аргументов: переменная, объявленная модулем с default, получает его, а объявленная без значения по умолчанию остаётся незаданной, поэтому Terraform отклоняет план.

Его ресурсы находятся в едином графе зависимостей границы. Ссылка или depends_on работает между подключением и компонентом, к которому оно подключено, и один terraform plan видит оба — то же свойство, которое структура «корень компонует потомков» даёт компонентам, по той же причине.

Его имена верхнего уровня принадлежат только ему. Поскольку описанное выше объединение пространства имён действует для каждого каталога, участник в собственном каталоге объявляет свои имена output, variable, resource и locals, не конфликтуя с соседями, — поэтому подключение может повторно использовать имя, уже объявленное его хостом, и ни одному не нужно знать, как другой что-либо назвал.

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

Поддерживаемые виды входных данных

Провайдер terraform принимает два из трёх видов входных данных сущности Recipe:

  • Режим artifacts. Сущность Recipe задаёт конфигурацию Terraform в виде шаблонного тела; провайдер вычисляет шаблон Aggrega и выводит результат, не переписывая его. HCL (main.tf) — удобный вариант по умолчанию, а Terraform JSON (.tf.json) принимается наравне с ним. Сведения о происхождении сборки проставляются блоком комментариев Terraform в начале тела HCL; для тела JSON, в котором нет синтаксиса комментариев, они записываются в сопутствующий файл aggrega.provenance.tf, а не внутрь тела.
  • Режим sourced. Сущность Recipe ссылается на модуль Terraform через source:. Файлы модуля дословно копируются (vendoring) в каталог этого компонента, а valuesMapping: сущности Recipe становится аргументами блока module этого компонента в корневой конфигурации границы. Тело модуля сохраняется точно в авторском виде, и в него ничего не записывается; значения указываются один раз, в корне, где их вычисляет Terraform. Если объявленные листья values узла напрямую становятся входами модуля — то есть у Recipe с source: нет valuesMapping:, — то для входа, несущего данные, которые автор объявил чувствительными, также генерируется файл переопределения с собственным атрибутом чувствительности Terraform; шаблон valuesMapping: сам придумывает имена своих выходов, поэтому в этом случае пометки нет, и сборка сообщает об этом предупреждением. Оба случая описаны в разделе Входы модуля, объявленные чувствительными.

null в valuesMapping: — это аргумент null. Ключ, которому сопоставление присваивает null, записывается в блоке модуля как <name> = null, и движок присваивает переменной модуля значение null, переопределяя её default, если только переменная не объявляет nullable = false — в этом случае применяется её default; чтобы вход получил значение модуля по умолчанию, не указывайте ключ в сопоставлении.

Вид входных данных synthesized не поддерживается. Не существует точного, агностичного к возможностям сопоставления вида Workload платформы с произвольными ресурсами Terraform, поэтому Recipe, объявляющая workload: для провайдера terraform, приводит к явной ошибке, а не к выдуманному преобразованию.

Recipe, объявляющая omits:, отклоняется. Ключ omits: исключает из сборки документы, которые отрисовывает источник, а этот провайдер ничего не отрисовывает из подключённого модуля во время сборки: он дословно копирует файлы модуля, и Terraform вычисляет их при планировании и применении конфигурации. Раз ничего не отрисовано, исключать нечего, поэтому этот провайдер не объявляет поддержку ключа, и Recipe или FeatureRecipe, объявляющая его, отклоняется до того, как что-либо будет скопировано, — см. The provider does not support omits (Провайдер не поддерживает omits). Для модуля, который хранится рядом с Recipe, исключить файл модуля можно строкой в расположенном там .aggregaignore — начиная со следующего закрепления Recipe.

Подключение модуля, опубликованного в реестре

Реестр модулей публикует каждую версию модуля как тег собственного git-репозитория модуля, а на запрос загрузки версии отвечает git-источником, закреплённым на коммите, на который указывает этот тег. Поэтому Recipe подключает опубликованный модуль из этого репозитория по этому тегу с видом источника git-repository:

spec:
capability: terraform
implements: example/storage/database:1.0.0
source:
kind: git-repository
url: https://github.com/terraform-aws-modules/terraform-aws-rds.git
ref: v7.2.2
valuesMapping: |
identifier: "{{ .values.identifier }}"
provides:
host: "${module.{{ .context.instance_id }}.db_instance_address}"
port: "${module.{{ .context.instance_id }}.db_instance_port}"

ref: — тег релиза точно в том виде, в каком его называет репозиторий. valuesMapping: задаёт входы модуля по именам, которые объявляют его блоки variable (Terraform требует значение для каждого входа без default), и они становятся аргументами блока module этого компонента в корневой конфигурации, как и для любого подключённого модуля.

Что закрепляется. aggrega pin и pull разрешают тег в коммит, на который он указывает, и архивируют репозиторий на этом коммите. Затем lock-файл сущности Release записывает этот коммит как закреплённую версию источника, тег — как указанную вами ссылку, а также дайджест архива. Каждая последующая сборка читает архив из кэша и проверяет его по этому дайджесту, прежде чем что-либо копировать, поэтому сеть ей не нужна, а кэшированный архив, байты которого больше не совпадают, останавливает сборку. Тег — это имя, которое в репозитории можно перенести на другой коммит; если последующий pull обнаружит, что ваш тег указывает на другой коммит, он остановится, а не примет новый коммит, а aggrega pull --upgrade принимает его намеренно. Это более строгое закрепление, чем собственный lock-файл зависимостей Terraform, который записывает выбранных конфигурацией провайдеров и вовсе не записывает модули, так что модуль, указанный в конфигурации как git-источник по тегу, зафиксирован лишь настолько, насколько зафиксирован тег. Здесь же коммит модуля и дайджест его байтов зафиксированы в lock-файле, байты скопированы в вывод, а корневая конфигурация вызывает их по локальному пути, поэтому движок ничего не загружает, чтобы загрузить сам модуль; модуль, который скопированный модуль вызывает из реестра или удалённого источника, всё равно загружается, и сборка сообщает о каждом таком вызове, как описано в разделе Вызов модуля, который движок загружает при инициализации.

Что копируется. Весь репозиторий на закреплённом коммите, кроме каталога .git/, попадает байт в байт в собственный каталог компонента в modules/: собственные файлы конфигурации модуля и дочерние модули, а также всё прочее, что есть в репозитории, — каталоги examples/ и wrappers/, документация, конфигурация CI и любые тестовые данные, включая двоичные. Движок читает только то, что вызывает модуль: когда корневая конфигурация вызывает каталог компонента, движок загружает файлы конфигурации непосредственно в нём и в каждом каталоге, куда оттуда ведёт локальный source. Поэтому каталог примеров, вызывающий другие модули из реестра, копируется, но никогда не загружается, и ничего из того, что он вызывает, не загружается из сети.

Сужение копируемого. Загруженный источник — это архив, в виде которого он был загружен, поэтому единственный способ сузить его — module_subdir:, который делает артефактом один каталог репозитория. Это помогает, только если нужный модуль находится в подкаталоге: модулю в корне репозитория, который вызывает свои ./modules/*, нужно всё дерево. Ни .terraformignore из репозитория, ни .aggregaignore рядом с Recipe не меняют того, что копирует загруженный источник: оба влияют на модуль, хранящийся рядом с Recipe, и ни один не читается для модуля, загруженного из репозитория.

Чтение того, что публикует модуль. Значение, которое публикует модуль, — это один из его блоков output, и потребитель читает его как ${module.<name>.<output>}, где <name> — блок модуля производителя; именно поэтому производитель выше публикует ${module.{{ .context.instance_id }}.<output>}. Движок разрешает ссылку по собственным блокам output модуля при проверке корневой конфигурации, поэтому имя выхода, которое модуль не объявляет, отклоняется на этом этапе с указанием этого имени:

Error: Unsupported attribute
on aggrega.modules.tf line 9, in module "api":
9: db_host = "${module.db.db_instance_addresz}"
This object does not have an attribute named "db_instance_addresz".

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

Дословный вывод и вендоринг

Провайдер terraform не транспилирует, не переформатирует и не переписывает тела Terraform. Написанное автором тело HCL или .tf.json выводится в точности так, как его вычисляет шаблон, причём тело HCL начинается с комментариев о происхождении, а подключённый модуль вендорится файл в файл. Именно это делает вывод terraform детерминированным и воспроизводимым: при одних и тех же входных данных отрисованная конфигурация побайтно совпадает от запуска к запуску, а вендоренный модуль проходит полный цикл без изменений. Поскольку провайдер никогда не разрешает состояние времени выполнения, всё, что зависит от времени выполнения, остаётся строкой интерполяции, которую Terraform связывает во время apply.

Аннотации платформы

Провайдер terraform не читает ни одной из аннотаций aggrega.ai/. У вендорированного модуля, файлов артефактов сущности Recipe и корневой конфигурации, которую записывает провайдер, нет места для пространства имён, префикса реестра, секрета для загрузки образов или сервисной учётной записи, поэтому значение, заданное для любого из них, ничего не меняет в отрисованной конфигурации; модуль, которому нужно такое значение, получает его как один из своих собственных входных параметров через values компонента.

Провайдер заявляет об этом в своей сущности Plugin с помощью readsNoWellKnownAnnotations: true (см. сущность Plugin), поэтому сборка выдаёт предупреждение о каждой аннотации aggrega.ai/, которая доходит через него до рендера, — по одному разу на ключ и на рендер, с указанием видов входных данных, которые объявляет этот рендер:

warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored it

Значение по-прежнему проходит через сборку без изменений, и сборка не останавливается: аннотация границы каскадом распространяется на каждый компонент под ней, а граница, компоненты которой рендерятся через разные цели, — обычная ситуация, а не ошибка. Предупреждение относится к классу unsupported-field и отключается флагом этого класса.

Входные данные модуля, объявленные чувствительными

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

Когда входные данные вендоренного модуля содержат материал, который автор объявил чувствительным, провайдер добавляет рядом с модулем ещё один файл, aggrega_override.tf.json, объявляющий sensitive = true для этих входных данных:

{
"variable": {
"db_password": {
"sensitive": true
}
}
}

Terraform объединяет файл конфигурации, имя которого — просто override или оканчивается на _override, с конфигурацией в том же каталоге, поэтому собственный блок variable модуля получает атрибут, а каждый вендоренный байт остаётся в точности таким, как написан. Объявленный тип, значение по умолчанию и описание входных данных не затрагиваются — override несёт атрибут чувствительности и ничего больше. Неотмеченный узел такого файла не получает.

Это ограничение намеренное, а не навязанное форматом файла: ничто в override не запрещает второй атрибут, и default блока variable — ближайшее место, к которому можно было бы обратиться, чтобы передать значение в вендоренный модуль, не редактируя его байты, — но значение не дошло бы. default в синтаксисе конфигурации JSON, на котором написан этот файл, — не та позиция, которую Terraform вычисляет, поэтому значение с указателем ${ ... }, записанное там, попадает в модуль как буквальные символы указателя, причём plan проходит успешно и ничего не сообщает. Тот же указатель, записанный в default в нативном HCL, сразу отклоняется, так что это молчание присуще данному синтаксису, а не файлам override как таковым. Поэтому override несёт только sensitive: его смысл не зависит от вычисления.

Какие входные данные отмечаются, определяет объявление, а не имя. Провайдер читает отметку, вычисленную компиляцией, и сам ничего не анализирует: он не распознаёт password, secret или token и не читает текст модуля, чтобы угадать. Входные данные модуля с именем db_password, значение которых не несёт объявления, выводятся неотмеченными, а объявленные входные данные с именем region отмечаются.

Отметка передаётся только туда, где идентичность входных данных восстанавливается из объявления. Сущность Recipe, которая вендорит модуль через source: и позволяет объявленным листьям values узла напрямую стать входными данными модуля, даёт каждому входу то же имя, которое объявил автор, поэтому связь точна, — и то же делает сущность FeatureRecipe сущности Feature, прикреплённой к компоненту, который вендорит модуль тем же способом, для листьев, объявленных её Feature. Сущность Recipe или такая FeatureRecipe, которая преобразует эти значения через шаблон valuesMapping:, придумывает собственные имена выходов, и никакое объявление их не называет, — поэтому отметка отсутствует, а не приближается, и сборка сообщает об этом одним предупреждением на каждый объявленный лист, называя лист и сущность, которой принадлежит отображение (Feature, прикреплённая к границе, отрисовывается вообще без values, поэтому ей нечего отмечать и предупреждений она не вызывает); см. A declared-sensitive value reaches the target through a values mapping (Значение, объявленное чувствительным, достигает цели через отображение значений). Отсутствие намеренно: угадывание того, какой преобразованный вход нёс объявленные данные, отметило бы публичный вход как секретный, и Terraform скрывал бы в выводе plan значение, которое никогда не было чувствительным.

Рабочий пример terraform-declared-sensitivity строит всё это от начала до конца и достаточно мал, чтобы прочитать его целиком: один компонент объявляет три листа values, два из которых несут публичные идентификаторы, а один — учётные данные. Его отрисованный вывод показывает, что аргументы блока module несут все три входа модуля, а override называет только объявленный, так что обе половины правила видны в одной сборке — в том числе то, что идентификатор учётных данных рядом с секретом остаётся неотмеченным. Если удалить единственное объявление и пересобрать, файл override не создаётся вовсе.

Что sensitive в Terraform гарантирует и чего не гарантирует

Aggrega обещает ровно то, что даёт собственный атрибут Terraform, и не более.

Он ограничивает отображение. Чувствительное значение выводится как (sensitive value) в выводе plan и как <sensitive> в выводе apply. Отметка распространяется через выражения, поэтому значение, производное от чувствительного входа, тоже чувствительно, и Terraform отказывается экспортировать такое значение из корневого output, который сам не отмечен как чувствительный, — громкая ошибка вместо тихого раскрытия.

Он не меняет хранение и не является шифрованием. Terraform записывает чувствительное значение в state в открытом виде. Воспринимать sensitive = true как обещание, что state безопасно коммитить или передавать, — именно то неверное толкование, которого следует избегать: защита state по-прежнему зависит от настройки бэкенда state, точно так же, как для модуля вообще без отметки. Атрибут также не ограничивает, кто может прочитать значение, не влияет на то, что передаёт провайдер, и никак иначе не меняет отрисованную конфигурацию.

Таким образом, отметка затрудняет случайное раскрытие входа, объявленного чувствительным, когда кто-то читает plan. Она не делает развёртываемый артефакт безопасным для публикации. Ключевое слово и то, чего достигает объявление для всех целей, описаны в разделе Объявление листа чувствительным.

Структурная проверка входных данных

Провайдер terraform проверяет структуру подключаемого модуля до рендеринга. Он разбирает файлы HCL и .tf.json модуля и сообщает об ошибках разбора, останавливая сборку с понятным сообщением, в котором указаны проблемный узел и провайдер. Разбор проверяет форму, а не семантику: он не разрешает провайдеры, не вычисляет выражения и не обращается к реестру. Проверка герметична: она использует автономный парсер HCL, скомпилированный в провайдер, без бинарного файла terraform и без доступа к сети. Некорректный модуль обнаруживается на границе авторинга, а не всплывает непонятной ошибкой при последующем запуске terraform.

Вызов модуля, который движок загружает при инициализации

Тот же разбор сообщает — предупреждением, которое ничего не отклоняет, — о каждом блоке module, источник которого Terraform загружает при инициализации конфигурации. Коммит и дайджест архива вендорированного модуля зафиксированы в lock-файле, но блок module внутри него, у которого source — адрес реестра, URL репозитория git или Mercurial или HTTP-архива, бакет S3 или GCS либо абсолютный путь, указывает на модуль, который движок загружает при инициализации в той версии, которую он тогда выберет, — а собственный lock-файл зависимостей Terraform фиксирует только провайдеры, так что этот модуль ничем не закреплён. О локальном source, выходящем за пределы вендорированного модуля, тоже сообщается, поскольку он указывает на файлы, которые сборка не вендорировала. Каждое сообщение называет узел и провайдер, затем блок, файл и строку, в которой он находится, и источник в том виде, в каком он записан:

warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that module

Что читается. Файлы, которые движок загружает при вызове модуля: файлы конфигурации непосредственно в собственном каталоге модуля, затем файлы в каждом каталоге, куда оттуда ведёт локальный source — начинающийся с ./ или ../ либо с их вариантов с обратной косой чертой, — с переходом от каталога к каталогу и однократным чтением каждого. Каталог, который никто не вызывает, не читается, поэтому о вызовах из каталогов examples/ или tests/ модуля не сообщается: движок никогда не загружает их при вызове модуля, и ничего из того, что они вызывают, не загружается. Описанная выше проверка разбора по-прежнему разбирает каждый вендорированный файл конфигурации. Авторское тело сущности Recipe при рендеринге читается так же, начиная с каталога, в который тело записывается, поэтому о блоке module, который авторское тело записывает с источником из реестра, тоже сообщается. Файл в spec.boundary.artifacts вычисляется и записывается самим компилятором и не передаётся никакому провайдеру, поэтому блок module, записанный в таком файле, не читается и предупреждения не вызывает.

Что не читается. Читается только то, что указано в source. Сборка не читает модуль, на который указывает вызов, не оценивает, что этот модуль делает, и не решает, допустим ли вызов. Значение source, которое движок вычисляет, а не читает как записано, — содержащее интерполяцию или ссылку, — оценивается по начальному тексту: о значении, начинающемся с адреса, сообщается как записано, а значение, начинающееся с локального префикса или с самой интерполяции, не сообщается и не отслеживается, поскольку то, куда оно ведёт, в тексте не указано. source внутри required_providers указывает на провайдер, а не на модуль, и вызовом модуля не является.

Почему об этом сообщается, а не отклоняется. Модуль, вызывающий другой модуль, — допустимые входные данные: Terraform загружает вызываемый модуль, и конфигурация работает. Автор при этом отказывается от закрепления вызываемого модуля сборкой — это факт, который полезно знать, а не ошибка, которую нужно исправить, и допустима ли такая загрузка, решает автор. Конфигурация, которая должна оставаться полностью закреплённой, вендорирует только модули, не делающие таких вызовов. Предупреждение, его код класса и то, где ещё оно проявляется, описаны в разделе Warnings and Linter Output.

Граница патчей FeatureRecipe

Шаг pipeline сущности FeatureRecipe, выполняемый после рендеринга, патчит только тот вывод, который провайдер рендерит в структурированное дерево. Для terraform это означает следующее:

  • Terraform, написанный в JSON, поддаётся патчам. Модуль .tf.json — структурированный документ, поэтому JSONPatch шага конвейера изменяет адресуемые значения на месте и оставляет все остальные байты — порядок, форматирование, соседние ключи — нетронутыми.
  • Нативный HCL непрозрачен. Тело на нативном HCL (main.tf) не является структурированной целью патча. Патч против непрозрачного тела останавливает сборку с диагностикой, а не изменяет текст, который невозможно адресовать структурно; шаг конвейера, написанный против тела HCL, — это ошибка проектирования, которая проявляется громкой остановкой, а не молчаливым отсутствием действия.
  • Входные данные подключаемого модуля вообще не являются целью патча. Это аргументы блока module компонента, который находится в корневой конфигурации: это нативный HCL, а значит, непрозрачный, и артефакт всей границы, а не какого-либо одного узла. Шаг pipeline патчит собственный отрендеренный вывод узла, поэтому нет позиции, из которой их можно было бы адресовать.

Поэтому автору, которому нужно, чтобы тело Terraform можно было патчить в конвейере, следует писать его как .tf.json. Общая граница целей патча для всех провайдеров описана в разделе FeatureRecipe.

Порядок развёртывания

Значение syncWave: границы сущности Release упорядочивает блоки module корневой конфигурации, в которую собирается эта граница. Каждый компонент границы наследует волну границы, а там, где несколько границ разрешаются в один и тот же выходной каталог — так что их компоненты объединяются в одну корневую конфигурацию, — этот корень содержит больше одной волны, и провайдер выражает порядок между ними как depends_on в блоках module.

Каждый модуль называет все модули непосредственно предшествующей волны, в которой есть хоть один компонент, и никакой более ранней волны. Остальное Terraform выстраивает в цепочку: модуль волны 2 зависит от волны 1, которая зависит от волны 0, поэтому вся последовательность упорядочена, а собственный список каждого модуля остаётся размером с одну волну, а не со всю границу. Волны не обязаны идти подряд, и отрицательные значения вполне обычны — -1 часто выбирают для бакета или роли, которые читает остальная конфигурация. Самая нижняя волна ничего не называет, потому что ей ничего не предшествует.

Что представляет собой этот порядок: порядок, в котором Terraform выполняет свои действия. Terraform строит граф зависимостей и обходит его параллельно в той мере, в какой позволяет граф. depends_on добавляет в этот граф ребро, поэтому Terraform завершает действия над названными модулями, прежде чем начать действия над модулем, объявляющим зависимость. Таким образом, волна разбивает выполнение на этапы: над компонентами более ранней волны действия выполняются до того, как начнутся действия над компонентами более поздней.

Это не упорядочивание по готовности. Конфигурация Terraform не выражает понятия работоспособности ресурса, поэтому здесь ничто не ждёт, пока ресурс станет готов, — только пока Terraform закончит действия над ним. Это реальное отличие от той же волны в compose, где сервис, объявляющий healthcheck, ожидается, пока не сообщит о работоспособности: у compose есть примитив готовности, по которому можно ставить барьер, а у конфигурации Terraform его нет. Порядок действий — это то, что предлагает данная цель, и сказать это прямо полезнее, чем приложить оговорку к обещанию, которое она не может дать.

Порядок удаления не обещается. depends_on утверждает, что Terraform завершает действия над зависимостью, прежде чем начать действия над зависимым; порядок, в котором destroy их удаляет, в это утверждение не входит, поэтому здесь ничего не утверждается о последовательности удаления. Это более узкое обещание, чем у той же волны в cloudformation, где атрибут управляет обоими направлениями, — это стоит знать, если вы рассчитываете, что волна упорядочит удаление, потому что на этой цели она этого не делает.

Граница, все компоненты которой несут одну волну, ничего от этого не получает. Как и сущность Release, которая вообще не объявляет syncWave: каждый участник несёт значение поля по умолчанию 0, корневая конфигурация содержит одну волну, а выводимые байты в точности такие же, какими были бы, если бы провайдер не выражал упорядочивание по волнам.

Порядок между двумя корневыми конфигурациями невыразим, и он не аппроксимируется. Граф зависимостей Terraform строится для каждой конфигурации отдельно, а depends_on называет модуль внутри конфигурации, которая его объявляет, поэтому волна упорядочивает все компоненты, объединённые в этот корень, и ничего за его пределами. Упорядочивание двух конфигураций — забота оператора, так же как ссылка на remote state разрешается во время развёртывания, а не во время сборки.

Волна не только учитывается при выполнении, но и записывается: она передаётся вместе с остальными сведениями о происхождении сборки узла — как aggrega.ai/sync-wave в проставленном блоке комментариев или в сопутствующем файле происхождения, если тело записано в JSON или является вендоренным модулем. Таким образом, отрендеренная конфигурация не только упорядочена по волне, объявленной её границей, но и фиксирует эту волну.

Порядок, который волны не выражают, остаётся собственной заботой Terraform, и значительную его часть уже несут ссылки между ресурсами: ссылка на атрибут другого ресурса указывает Terraform сначала выполнить действия над этим ресурсом. Модуль, которому нужно ограничение, не следующее ни из ссылок, ни из волн, сам записывает depends_on внутри модуля, и провайдер выводит его дословно, как и любую другую часть тела.