Несколько команд в организации используют общий модуль Terraform из внутреннего Git-репозитория для создания виртуальных машин. После обновления модуля без изменения версии в коде потребителей у части команд внезапно поменялось поведение apply. Как правильно фиксировать версию модуля при подключении, и какие риски создаёт отсутствие версионирования модулей?

Короткий ответ

Версию модуля нужно явно указывать через параметр version (для модулей из Terraform Registry) или через ref на конкретный тег/коммит Git (?ref=v1.4.0) в source, а не на main/master; без фиксированной версии любое обновление кода модуля немедленно и незаметно влияет на всех потребителей при следующем terraform init -upgrade или даже при обычном init, если источник модуля не закреплён на неизменяемый коммит.

Как это работает подробнее

Terraform скачивает код модуля из source при terraform init и кладёт его в .terraform/modules; если source указывает на изменяемую ссылку (ветку), содержимое модуля может отличаться при каждой переустановке, а сам Terraform не хранит версию модуля в своём state как отдельную проверяемую величину — он просто применяет то, что скачал.

Пример кода

main.tfКопировать

module "vm" {
  source  = "git::https://git.acme.local/infra/terraform-modules.git//vm?ref=v1.4.0"
}
# или модуль из приватного registry:
module "vm" {
  source  = "app.terraform.io/acme/vm/aws"
  version = "~> 1.4"
}

Что использовать на практике

• Практика. в организации стоит вести модули в отдельных репозиториях с семантическим версионированием и CHANGELOG, публиковать их либо во внутренний Terraform Registry, либо фиксировать ref на git-тег; обновление версии модуля в конфигурациях-потребителях должно проходить через обычный plan/review, чтобы видеть эффект изменений до применения, а не как побочный эффект чужого коммита.

Подводные камни

• Ошибка. частая ошибка — ссылаться на ref=main «для простоты», из-за чего любое изменение модуля сразу раскатывается на всех потребителей без code review на их стороне; другая ошибка — не вести CHANGELOG и breaking-change политику для внутренних модулей, из-за чего потребители не понимают, что при переходе с v1 на v2 изменились обязательные переменные.