Синтаксис

https://developer.hashicorp.com/terraform/language/syntax/configuration

Синтаксис конфігурації

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

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

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

Аргументи та блоки

Синтаксис мови Terraform побудовано навколо двох ключових синтаксичних конструкцій: аргументів та блоків.

Аргументи

Аргумент присвоює значення певному імені:

image_id = "abc123"

Ідентифікатор перед знаком рівності - це ім'я аргументу, а вираз після знаку рівності - значення аргументу.

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

Примітка: Мова конфігурації Terraform базується на більш загальній мові, яка називається HCL, і в документації до HCL зазвичай використовується слово "атрибут" замість "аргумент". Ці слова досить схожі, щоб бути взаємозамінними в даному контексті, і досвідчені користувачі Terraform можуть використовувати обидва терміни в повсякденній розмові. Але оскільки Terraform також взаємодіє з деякими іншими речами, які називаються "атрибутами" (зокрема, ресурси Terraform мають атрибути, такі як id, на які можна посилатися у виразах, але яким не можна присвоювати значення у конфігурації), ми вирішили використовувати термін "аргумент" у документації Terraform, коли йдеться про цю синтаксичну конструкцію.

Блоки

Блок - це контейнер для іншого вмісту:

resource "aws_instance" "example" {
  ami = "abc123"

  network_interface {
    # ...
  }
}

Блок має тип (у цьому прикладі - resource). Кожен тип блоку визначає, скільки міток має бути після ключового слова type. Тип блоку resource очікує дві мітки, якими у наведеному вище прикладі є aws_instance та example. Певний тип блоку може мати будь-яку кількість необхідних міток, або не вимагати жодної, як у випадку з вкладеним типом блоку network_interface.

Після ключового слова типу блоку і будь-яких міток, тіло блоку відокремлюється символами { і }. У тілі блоку можуть бути вкладені інші аргументи та блоки, створюючи ієрархію блоків та пов'язаних з ними аргументів.

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

Ідентифікатори

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

Ідентифікатори можуть містити літери, цифри, знаки підкреслення (_) та дефіси (-). Перший символ ідентифікатора не повинен бути цифрою, щоб уникнути двозначності з буквеними числами.

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

Коментарі

Мова Terraform підтримує три різні синтаксиси для коментарів:

# починає однорядковий коментар, який закінчується у кінці рядка
// також починає однорядковий коментар, як альтернатива #
/* та */ є початковим та кінцевим розділювачами для коментаря, який може займати декілька рядків.

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

Кодування символів і закінчення рядків

Файли конфігурації Terraform завжди повинні бути в кодуванні UTF-8. Хоча розділювачі мови є символами ASCII, Terraform приймає не-ASCII символи в ідентифікаторах, коментарях та рядкових значеннях.

Terraform приймає конфігураційні файли із закінченнями рядків у стилі Unix (тільки LF) або у стилі Windows (CR, потім LF), але ідіоматичним стилем є використання угод Unix, тому інструменти автоматичного форматування конфігурації можуть автоматично перетворювати CRLF-закінчення на LF.

Стандарт кодування

https://developer.hashicorp.com/terraform/language/syntax/style

Угоди щодо стилів

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

[!TIP] Ви можете застосувати ці домовленості автоматично, запустивши terraform fmt.

Для кожного рівня вкладеності зробіть відступ у два пробіли.
Якщо декілька аргументів з однорядковими значеннями з'являються у послідовних рядках на одному рівні вкладеності, вирівняйте їхні знаки рівності:
```
ami           = "abc123"
instance_type = "t2.micro"
```
Коли аргументи і блоки з'являються разом у тілі блоку, розмістіть всі аргументи разом у верхній частині, а потім розмістіть вкладені блоки під ними. Відокремлюйте аргументи від блоків одним порожнім рядком.
Використовуйте порожні рядки для відокремлення логічних груп аргументів всередині блоку.
Для блоків, які містять як аргументи, так і "мета-аргументи" (згідно з визначенням семантики мови Terraform), спочатку перелічіть мета-аргументи і відокремте їх від інших аргументів одним порожнім рядком. Блоки з мета-аргументами розміщуйте останніми і відокремлюйте їх від інших блоків одним порожнім рядком.
```
resource "aws_instance" "example" {
    count = 2 # meta-argument first

    ami           = "abc123"
    instance_type = "t2.micro"

    network_interface {
      # ...
    }

    lifecycle { # meta-argument block last
      create_before_destroy = true
    }
}
```
Блоки верхнього рівня завжди слід відокремлювати один від одного одним порожнім рядком. Вкладені блоки також слід відокремлювати порожніми рядками, за винятком випадків, коли вони групують пов'язані блоки одного типу (наприклад, декілька блоків provisioner у ресурсі).
Уникайте групування декількох блоків одного типу з іншими блоками іншого типу, якщо тільки типи блоків не визначені семантикою для формування сімейства. (Наприклад: root_block_device, ebs_block_device та ephemeral_block_device на aws_instance утворюють сімейство типів блоків, що описують блокові пристрої AWS, і тому можуть бути згруповані разом і змішані).

Синтаксис

Синтаксис