Каким образом terraform понимает в каком файле что написано?

Отвечая на этот вопрос, важно понимать, что мы рассматриваем не внутреннюю реализацию Terraform (это закрытый код HashiCorp), а его общедоступное поведение и логику, которую можно наблюдать и которая задокументирована.

Как Terraform обрабатывает файлы конфигурации

Terraform использует свой собственный HCL (HashiCorp Configuration Language) парсер, который является частью библиотеки hcl. Этот парсер применяет ряд последовательных шагов для понимания содержимого файлов.

1. Фаза парсинга (Parsing Phase)

Первая задача — преобразовать текст файла в абстрактное синтаксическое дерево (AST).

• Расширение файлов: Terraform автоматически читает все файлы в рабочей директории с расширениями .tf и .tf.json. Он также может читать файлы с другими расширениями, если они указаны явно в командной строке (например, terraform plan -target=module.vpc).
• Обработка HCL: Для файлов .tf используется парсер HCL.
• Обработка JSON: Для файлов .tf.json используется стандартный JSON парсер, а затем результат преобразуется в структуры HCL. JSON-формат менее удобен для чтения, но может быть полезен для автоматической генерации конфигураций.
• Ключевое правило: Terraform не выполняет никакой "умной" логики на этой стадии (например, объединение ресурсов из разных файлов по типу). Он просто читает все файлы и строит единое AST для всей конфигурации. Порядок файлов и расположение блоков внутри них на этом этапе не имеют значения.

# Это содержимое файла `main.tf`
resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

# Это содержимое файла `network.tf`
resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
}

Terraform соберет AST из обоих файлов, как если бы они были одним большим файлом.

2. Фаза анализа конфигурации (Configuration Analysis Phase)

После того как AST построено, начинается этап семантического анализа.

• Объединение и группировка: Terraform анализирует AST и группирует все найденные блоки по их типам:

    *   `resource` блоки группируются по типу ресурса (например, все `aws_instance`) и по имени (например, все ресурсы с именем `web`).
    *   `data` блоки обрабатываются аналогично `resource`.
    *   `variable`, `output`, `locals`, `provider` блоки также группируются.

• Важный принцип: Terraform требует, чтобы все блоки одного типа и с одним логическим именем были уникальными в рамках всей конфигурации (всех файлов). Нельзя иметь два resource "aws_instance" "web" в разных файлах — это вызовет ошибку Duplicate resource declaration.
• Зависимости и ссылки: Парсер определяет ссылки между объектами (например, когда aws_instance.web ссылается на aws_vpc.main.cidr_block через переменную). Это позволяет Terraform позже построить граф зависимостей.

3. Ключевые особенности поведения

• Отсутствие импорта или включения файлов: В Terraform нет директив import или include. Все .tf файлы в директории автоматически считаются частью одной конфигурации.
• Модули (Modules): Для организации конфигурации используется концепция модулей. Каждый модуль — это отдельная директория с своими .tf файлами. При вызове модуля в корневой конфигурации (module "vpc" { ... }) Terraform обрабатывает файлы этого модуля отдельно, в его собственном контексте. Это обеспечивает изоляцию и повторное использование.
• Переопределение (Overrides): Существуют специальные файлы с расширениями .tfvars или terraform.tfvars (и .tfvars.json), которые содержат значения для переопределения переменных (variable). Они не содержат ресурсов или провайдеров. Terraform обрабатывает их в отдельной фазе, после анализа основной конфигурации, для подстановки конкретных значений.
• Состояние (State): Файлы конфигурации описывают желаемое состояние. Как это состояние соотносится с уже созданной инфраструктурой, Terraform определяет путем сравнения конфигурации с содержимым файла состояния (terraform.tfstate). Файлы конфигурации и файл состояния — это разные сущности.

Пример конфликта и его разрешения

# File: first.tf
resource "aws_security_group" "alb" {
  name = "alb-sg"
}

# File: second.tf
resource "aws_security_group" "alb" {
  name = "alb-security-group"
}

При запуске terraform validate или terraform plan вы получите ошибку:

Error: Duplicate resource declaration

A aws_security_group resource named "alb" was already declared at first.tf:1,1.
It cannot be declared again at second.tf:1,1.

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

Выводы для DevOps-инженера

1. Организация файлов — вопрос удобства, не функционала. Вы можете разбивать конфигурацию на файлы по логическим группам (network.tf, compute.tf, database.tf), по типу объектов (resources.tf, variables.tf, outputs.tf) или даже держать все в одном main.tf. Terraform воспримет это одинаково.
2. Уникальные идентификаторы — ключевое правило. Самый важный аспект при работе с несколькими файлами — обеспечить уникальность комбинации тип + имя для resource, data, module.
3. Модули — основной инструмент структурирования. Для создания сложных, повторно используемых или изолированных компонентов инфраструктуры используйте модули, а не просто множество файлов в одной директории.
4. .tfvars — для значений, не для деклараций. Эти файлы предназначены исключительно для передачи значений переменным и не влияют на то, "что" создается (ресурсы), только на "как" (их параметры).

Таким образом, Terraform "понимает", что написано в файлах, путем их сквозного парсинга в единое AST, а затем семантического анализа и группировки всех найденных деклараций в рамках одной корневой конфигурации или модуля.