Ресурси

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

resource "aws_instance" "web" {
    ami           = "ami-a1b2c3d4"
    instance_type = "t2.micro"
}

• Блоки ресурсів документують синтаксис оголошення ресурсів.
• Поведінка ресурсів докладніше пояснює, як Terraform обробляє оголошення ресурсів при застосуванні конфігурації.

У розділі «Мета-аргументи» описані спеціальні аргументи, які можна використовувати з кожним типом ресурсу, включаючи depends_on, count, for_each, provider і lifecycle.

• Документи Provisioners налаштовують дії після створення ресурсу з використанням блоків provisioner і connection. Оскільки постачальники є недекларативними та потенційно непередбачуваними, ми настійно рекомендуємо використовувати їх у крайньому випадку.

Типи ресурсів

Кожен ресурс пов'язаний з одним типом ресурсу, який визначає тип об'єкта інфраструктури, яким він керує, та які аргументи та інші атрибути підтримує ресурс.

Провайдери

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

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

Terraform зазвичай автоматично визначає, який провайдер використовувати, виходячи з імені типу ресурсу. (За згодою імена типів ресурсів починаються з переважного локального імені їхнього провайдера.) При використанні кількох конфігурацій провайдера (або небажаних імен локальних провайдерів) необхідно використовувати метааргумент, щоб вручну вибрати альтернативну конфігурацію провайдера provider.

Аргументи ресурсу

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

Значення аргументів ресурсів можуть повною мірою використовувати вирази та інші динамічні функції Terraform.

Є також деякі метааргументи, які визначені самим Terraform і застосовуються до всіх типів ресурсів.

Документація за типами ресурсів

Кожен постачальник Terraform має власну документацію, яка описує типи ресурсів та їх аргументи.

Більшість загальнодоступних провайдерів розповсюджуються в Terraform Registry, де також розміщується їхня документація. Під час перегляду сторінки постачальника в реєстрі Terraform можна клацнути посилання «Документація» в заголовку, щоб переглянути його документацію. Документація провайдера в реєстрі має версію, і ви можете використовувати меню версії в заголовку, щоб перемикатися між версіями документації, яку ви переглядаєте.

Поведінка ресурсів

Щоб отримати додаткові відомості про те, як Terraform керує ресурсами при застосуванні конфігурації, див. розділ Resource Behavior.

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

Застосування конфігурації Terraform — це процес створення, оновлення та знищення реальних об'єктів інфраструктури, щоб привести їх налаштування у відповідність до конфігурації.

Як Terraform застосовує конфігурацію

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

Таким чином, застосування конфігурації Terraform дозволить:

• Створювати ресурси, що у конфігурації, але з пов'язані з реальним об'єктом інфраструктури може.
• Знищувати ресурси, які існують у стані, але не існують у конфігурації.
• Оновляти ресурси на місці, аргументи яких змінилися.
• Знищувати та заново створювати ресурси, аргументи яких були змінені, але які не можна оновити на місці через обмеження віддаленого API.

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

Мета-аргументи всередині resource блоків дозволяють налаштовувати деякі деталі цієї стандартної поведінки ресурсів для кожного ресурсу.

Доступ до атрибутів ресурсів

Вирази в модулі Terraform можуть отримати доступ до інформації про ресурси в тому ж модулі, і ви можете використовувати цю інформацію, щоб допомогти налаштувати інші ресурси. Використовуйте синтаксис \<RESOURCE TYPE\>.\<NAME\>.\<ATTRIBUTE\> для посилання на атрибут ресурсу у виразі.

На додаток до аргументів, зазначених у конфігурації, ресурси часто надають атрибути тільки для читання з інформацією, отриманою з віддаленого API; це часто включає речі, які не можуть бути відомі до створення ресурсу, наприклад, унікальний випадковий ідентифікатор ресурсу.

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

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

Залежності ресурсів

Більшість ресурсів у конфігурації не пов'язані між собою, і Terraform може паралельно вносити зміни до кількох непов'язаних ресурсів.

Однак, деякі ресурси повинні оброблятися після інших певних ресурсів; іноді це пов'язано з тим, як працює ресурс, а іноді конфігурація ресурсу просто вимагає інформації, згенерованої іншим ресурсом.

Більшість залежностей між ресурсами обробляються автоматично. Terraform аналізує будь-які вирази в блоці resource, щоб знайти посилання на інші об'єкти, і розглядає ці посилання як неявні вимоги впорядкування при створенні, оновленні або знищенні ресурсів. Оскільки більшість ресурсів з поведінковими залежностями від інших ресурсів також посилаються на дані цих ресурсів, зазвичай немає необхідності вручну вказувати залежності між ресурсами.

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

Ви також можете використовувати мета-аргумент replace_triggered_by для додавання залежностей між незалежними ресурсами. Він змушує Terraform замінити батьківський ресурс при зміні ресурсу, на який він посилається, або атрибуту ресурсу.

Локальні ресурси

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

Наприклад, існують локальні типи ресурсів для генерації приватних ключів, видачі самопідписаних TLS-сертифікатів і навіть генерації випадкових ідентифікаторів. Хоча ці типи ресурсів часто мають більш маргінальне призначення, ніж ті, що керують "реальними" об'єктами інфраструктури, вони можуть бути корисними як клей, що допомагає з'єднати разом інші ресурси.

Поведінка локальних ресурсів така ж, як і всіх інших, але дані про їхні результати існують лише в межах стану Terraform. "Знищити" такий ресурс означає лише вилучити його зі стану, відкинувши його дані.

Мета-аргументи

Мова Terraform визначає декілька мета-аргументів, які можуть бути використані з будь-яким типом ресурсу для зміни поведінки ресурсів.

Наступні мета-аргументи задокументовані на окремих сторінках:

-depends_onдля визначення прихованих залежностей -countдля створення декількох екземплярів ресурсу за лічильником -for_eachдля створення декількох екземплярів відповідно до карти або набору рядків провайдер, для вибору конфігурації провайдера не за замовчуванням -lifecycleдля налаштування життєвого циклу -provisionerдля виконання додаткових дій після створення ресурсу

Синтаксис ресурсів

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

Ресурсний блок оголошує ресурс заданого типу ("aws_instance") із заданим локальним іменем ("web"). Ім'я використовується для посилання на цей ресурс з іншого місця в тому ж модулі Terraform, але не має ніякого значення за межами цього модуля.

Тип ресурсу та ім'я разом слугують ідентифікатором для даного ресурсу і тому повинні бути унікальними в межах модуля.

У тілі блоку (між { і }) знаходяться аргументи конфігурації для самого ресурсу. Більшість аргументів у цій секції залежать від типу ресурсу, і дійсно, у цьому прикладі і ami, і instance_type є аргументами, визначеними спеціально для типу ресурсу aws_instance.

Примітка: Назви ресурсів мають починатися з літери або символу підкреслення і можуть містити лише літери, цифри, підкреслення і тире.

Provisioners

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

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

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

Передача даних у віртуальні машини та інші обчислювальні ресурси

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

Різні провайдери, які взаємодіють з віддаленими серверами через SSH або WinRM, потенційно можуть бути використані для передачі таких даних шляхом входу на сервер і надання їх безпосередньо, але більшість платформ хмарних обчислень надають механізми для передачі даних екземплярам під час їх створення, таким чином, щоб дані були доступні відразу після завантаження системи. Наприклад: -Alibaba Cloud: user_data на alicloud_instance або alicloud_launch_template. -Amazon EC2: user_data або user_data_base64 в aws_instance, aws_launch_template і aws_launch_configuration. -Amazon Lightsail: user_data на aws_lightsail_instance. -Microsoft Azure: custom_data на azurerm_virtual_machine або azurerm_virtual_machine_scale_set. -Google Cloud Platform: метадані на google_compute_instance або google_compute_instance_group. -Хмарна інфраструктура Oracle: метадані або розширені метадані на oci_core_instance або oci_core_instance_configuration. -VMware vSphere: Приєднайте віртуальний CDROM до vsphere_virtual_machine за допомогою блоку cdrom, який містить файл з назвою user-data.txt.

До складу багатьох офіційних образів дисків дистрибутивів Linux входить програма cloud-init, яка може автоматично обробляти різними способами дані, передані описаними вище способами, що дозволяє запускати довільні скрипти і виконувати базові налаштування системи безпосередньо під час завантаження і без необхідності доступу до машини по SSH.

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

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

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

Запуск програмного забезпечення для керування конфігурацією

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

Ми наполегливо рекомендуємо не користуватися цими програмами, а виконувати кроки конфігурування системи під час створення власного образу. Наприклад, HashiCorp Packer пропонує подібний набір засобів керування конфігурацією і може запускати їхні кроки встановлення під час окремого процесу збирання перед створенням образу системного диска, який ви можете розгортати багато разів.

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

Як використовувати провізори

[!TIP] Провайдер слід використовувати лише в крайньому випадку. Для більшості поширених ситуацій існують кращі альтернативи. Для отримання додаткової інформації див. розділи вище.

Якщо ви впевнені, що провайдери є найкращим способом вирішити вашу проблему після розгляду порад у попередніх розділах, ви можете додати блок provisioner до блоку resource екземпляра обчислення.

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command = "echo The server's IP address is ${self.private_ip}"
  }
}

Провайдер local-exec не потребує інших налаштувань, але більшість інших провайдерів повинні підключатися до віддаленої системи за допомогою SSH або WinRM. Ви повинні включити блок connection, щоб Terraform знав, як зв'язатися з сервером.

Terraform має декілька вбудованих провайдерів. Ви також можете використовувати сторонні провайдери як плагіни, розмістивши їх у %APPDATA%\terraform.d\plugins, ~/.terraform.d/plugins або в тому ж каталозі, де встановлено двійковий файл Terraform. Однак, ми не рекомендуємо використовувати інші провізори, окрім вбудованого file, local-exec та remote-exec провізорів.

Об'єкт self

Вирази у блоках-провайдерах не можуть посилатися на батьківський ресурс за іменем. Замість цього вони можуть використовувати спеціальний об'єкт self.

Об'єкт self представляє батьківський ресурс провайдера і має всі атрибути цього ресурсу. Наприклад, використовуйте self.public_ip для посилання на атрибут public_ip екземпляра aws_instance.

Провайдери часу створення

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

Якщо у процесі створення відбувається збій, ресурс позначається як зіпсований. Зіпсований ресурс буде заплановано до знищення та відтворення при наступному terraform apply. Терраформ робить це тому, що невдалий провайдер може залишити ресурс у напівконфігурованому стані. Оскільки Terraform не може знати, що робить провайдер, єдиний спосіб забезпечити належне створення ресурсу - це відтворити його через знищення.

Ви можете змінити цю поведінку, встановивши атрибут on_failure, який детально описано нижче.

Провайдери з часом знищення

Якщо вказано when = destroy, провізор буде запущено, коли ресурс, в якому він визначений, буде знищено.

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    when    = destroy
    command = "echo 'Destroy-time provisioner'"
  }
}

Перед знищенням ресурсу запускаються провізори знищення. Якщо вони не спрацюють, Terraform видасть помилку і повторить запуск провізорів при наступному terraform apply. Через таку поведінку слід подбати про те, щоб знищити провізори безпечно запускати декілька разів.

Примітка: Знищення провізорів цього ресурсу не виконується, якщо параметру create_before_destroy присвоєно значення true.

Провайдерів часу знищення можна запускати, лише якщо вони залишаються у конфігурації на момент знищення ресурсу. Якщо блок ресурсу з провізором часу знищення повністю видаляється з конфігурації, його конфігурації провізорів видаляються разом з ним, і, таким чином, провізор часу знищення не буде запущено. Щоб обійти цю проблему, можна скористатися багатокроковим процесом для безпечного видалення ресурсу з пакувальником часу знищення: -Оновіть конфігурацію ресурсу, включивши до неї значення count = 0. -Застосуйте конфігурацію для знищення всіх наявних екземплярів ресурсу, включно із запуском планувальника знищення. -Повністю видаліть блок ресурсу з конфігурації разом з блоками provisioner. -Застосуйте конфігурацію знову, після чого не слід виконувати жодних подальших дій, оскільки ресурси вже було знищено.

Через це обмеження, ви повинні використовувати знищувані на час провізори економно і з обережністю.

[!TIP] Провайдер часу знищення на пошкодженому ресурсі не буде запущено. Це стосується ресурсів, які позначено як зіпсовані внаслідок невдалого попередника часу створення або зіпсовані вручну за допомогою terraform taint.

Кілька провайдерів

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

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

Приклад з декількома попередниками:

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command = "echo first"
  }

  provisioner "local-exec" {
    command = "echo second"
  }
}

Поведінка при збоях

За замовчуванням, збій провайдерів також призведе до збою програми Terraform. Параметр on_failure може бути використаний для зміни цього. Допустимими значеннями є

• continue - ігнорувати помилку і продовжити створення або знищення.
• fail - Згенерувати помилку і припинити застосування (поведінка за замовчуванням). Якщо це провайдер створення, зіпсуйте ресурс.

Приклад:

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command    = "echo The server's IP address is ${self.private_ip}"
    on_failure = continue
  }
}