Terraform Provider
Провайдер terraform рендерить сутності 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.tfComponents одного кореня, що оголошують той самий файл з тими самими байтами, спільно використовують одну копію; та сама назва з іншими байтами зупиняє збирання. Ресурси модулів записуються щодо цієї однієї конфігурації, тож саме з нею 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:. Файли модуля дослівно вендоряться в каталог цього компонента, а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-файлі, байти вендоряться у вихідні дані, а коренева конфігурація викликає їх за локальним шляхом, тож рушій нічого не завантажує, щоб завантажити сам модуль — модуль, який вендорений модуль викликає через реєстр або віддалене джерело, однаково завантажується, і збірка повідомляє про кожен такий виклик, як описано в розділі A module call the engine fetches when it initialises (Виклик модуля, який рушій завантажує під час ініціалізації).
Що вендориться. Увесь репозиторій на закріпленому коміті, крім каталогу .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 модуля отримує атрибут, а кожен вендорений байт лишається точно таким, як його написано. Оголошений тип, значення за замовчуванням і опис параметра не змінюються — перевизначення містить атрибут чутливості й нічого більше. Непозначений вузол такого файлу не отримує.
Це обмеження свідоме, а не накладене форматом файлу: ніщо в перевизначенні не забороняє другий атрибут, і default блоку variable — найближче місце, до якого можна було б удатися, щоб передати значення у вендорений модуль, не змінюючи його байтів, — але значення не дійшло б. default у синтаксисі конфігурації JSON, яким написано цей файл, — не та позиція, яку Terraform обчислює, тож значення з вказівником ${ ... }, записане там, доходить до модуля як буквальні символи вказівника, під час плану, який завершується успішно й нічого не повідомляє. Той самий вказівник, записаний у default у нативному HCL, відхиляється одразу, отже ця мовчазність властива саме цьому синтаксису, а не файлам перевизначення як таким. Тому перевизначення містить лише 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 тоді приховував би у виводі плану значення, яке ніколи не було чутливим.
Робочий приклад terraform-declared-sensitivity показує це від початку до кінця й досить малий, щоб прочитати його повністю: один компонент оголошує три листки values, з яких два містять публічні ідентифікатори, а один — облікові дані. Його відображений вивід показує, що аргументи блоку module містять усі три вхідні параметри модуля, а перевизначення називає лише оголошений, тож обидві половини правила видно в одній збірці — зокрема й те, що ідентифікатор облікових даних поруч із секретом лишається непозначеним. Якщо видалити це одне оголошення й перезібрати, файл перевизначення не виводиться взагалі.
Що sensitive у Terraform гарантує і чого не гарантує
Aggrega обіцяє рівно те, що забезпечує власний атрибут Terraform, і не більше.
Він обмежує відображення. Чутливе значення показується як (sensitive value) у виводі плану і як <sensitive> у виводі застосування. Позначка поширюється через вирази, тож значення, похідне від чутливого параметра, теж чутливе, і Terraform відмовляється експортувати його з кореневого output, який сам не позначено чутливим, — гучна помилка замість мовчазного розкриття.
Він не змінює зберігання і не є шифруванням. Terraform записує чутливе значення у стан у відкритому вигляді. Сприймати sensitive = true як обіцянку, що стан безпечно комітити чи поширювати, — це та єдина хибна інтерпретація, якої слід уникати: захист стану й надалі залежить від того, як налаштовано бекенд стану, точно так само, як і для модуля без жодної позначки. Атрибут також не обмежує, хто може читати значення, не впливає на те, що передає провайдер, і не змінює відображену конфігурацію жодним іншим чином.
Отже, позначка ускладнює випадкове розкриття параметра, оголошеного чутливим, коли хтось читає план. Вона не робить розгортуваний результат безпечним для публікації. Див. Оголошення листка чутливим, щоб дізнатися про ключове слово і про те, чого досягає оголошення для кожної цілі.
Структурна перевірка вхідних даних
Провайдер 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 завантажує викликаний модуль, і конфігурація працює. Автор втрачає лише закріплення збіркою викликаного модуля, і це факт, який варто знати, а не помилка, яку треба виправити; чи прийнятне таке завантаження — вирішує автор. Конфігурація, яка має залишатися повністю закріпленою, вендорить лише модулі, що не роблять таких викликів. Попередження, його код класу та інші місця, де воно проявляється, описано в розділі Попередження та виведення лінтера.
Межа патчів 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 називає модуль усередині конфігурації, яка його оголошує, тож хвиля впорядковує кожен компонент, скомпонований у цей корінь, і нічого поза ним. Упорядкування двох конфігурацій — справа оператора, так само як посилання на віддалений стан розв’язується під час розгортання, а не під час збирання.
Хвиля не лише впливає на виконання, а й записується: вона передається разом з рештою походження збирання вузла — як aggrega.ai/sync-wave у проставленому блоці коментарів або в супровідному файлі походження, якщо тіло у форматі JSON чи є вендореним модулем. Тож відрендерена конфігурація і впорядкована хвилею, і фіксує, яку хвилю оголосила її межа.
Порядок, якого хвилі не виражають, залишається справою самого Terraform, і значну його частину вже несуть посилання між ресурсами: посилання на атрибут іншого ресурсу вказує Terraform спершу виконати дії над тим ресурсом. Модуль, якому потрібне обмеження, що не випливає ні з посилань, ні з хвиль, пише власний depends_on усередині модуля, і провайдер виводить його дослівно, як і будь-яку іншу частину тіла.
Пов’язані довідники
- Архітектура Provider — як провайдери вбудовуються в конвеєр компіляції та диспетчеризацію за провайдерами.
- Покажчик довідки Provider — що створює кожен провайдер стандартної бібліотеки і яка сторінка відповідає на яке запитання.
- Сутність Recipe — інтерфейс створення сутності Recipe і три види вхідних даних.
- FeatureRecipe — модель патчів
pipelineпісля рендерингу та її межа між структурованим і непрозорим. - Композиція вхідних даних Recipe — канонічна матриця можливостей сутностей Provider.