Lock-файл Terraform и OpenTofu: фиксируем версии и проверяем обновление провайдера

На ноутбуке plan без изменений, а в CI после init появились новые предупреждения и другой diff. Конфигурация содержит ограничение ~> 3.6, но это диапазон, а не одна версия пакета. Если выбранная версия и контрольные суммы не зафиксированы одинаково, окружения могут установить разные допустимые providers.

Файл .terraform.lock.hcl хранит решение о выборе provider и известные checksums пакетов. Его обычно коммитят вместе с конфигурацией. Каталог .terraform содержит установленные файлы и служебные данные рабочего каталога; его содержимое не заменяет lock-файл в репозитории.

Ограничение и выбор решают разные задачи

В новом учебном каталоге объявите provider random. В примере указан полный адрес registry.terraform.io, чтобы источник был одинаково явным в Terraform и OpenTofu. Если команда использует registry.opentofu.org, выберите и зафиксируйте соответствующий source отдельно.

terraform {
  required_providers {
    random = {
      source  = "registry.terraform.io/hashicorp/random"
      version = "~> 3.6.0"
    }
  }
}

resource "random_id" "demo" {
  byte_length = 4
}

Terraform init или tofu init выбирает допустимую версию и создаёт lock-файл. Ограничение ~> 3.6.0 допускает патч-версии ветки 3.6, но исключает 3.7. Выбранная точная version будет записана в lock. При следующем обычном init инструмент старается использовать зафиксированное решение, если оно удовлетворяет ограничениям.

Проверим отсутствие незаметного обновления

terraform init -lockfile=readonly
terraform plan

tofu init -lockfile=readonly
tofu plan

Выберите свой набор команд. Readonly подходит для CI, который должен использовать проверенный выбор, а не дописывать lock по ходу релиза. Если конфигурация требует другую версию, ошибка инициализации становится поводом обновить зависимости отдельной правкой. Она не должна лечиться удалением lock в каждом pipeline.

Для осознанного обновления сначала измените ограничение при необходимости, затем выполните init -upgrade и рассмотрите diff lock-файла. Upgrade ищет новые допустимые решения. После него нужен новый plan и проверка заметных изменений provider, а не только подтверждение скачивания пакета.

Контрольные суммы зависят и от платформы

Один provider выпускается отдельными пакетами для разных ОС и архитектур. Ситуация «macOS проходит, Linux CI не проходит checksum» требует проверить источник пакета, платформы и способ наполнения lock. В согласованном процессе можно заранее записать checksums нужных платформ через providers lock.

terraform providers lock -platform=linux_amd64 -platform=darwin_arm64

tofu providers lock -platform=linux_amd64 -platform=darwin_arm64

Эти команды обращаются к источникам provider и меняют lock-файл, поэтому их результат тоже проходит ревью. При использовании filesystem/network mirror учитывайте, откуда получены контрольные суммы и подписи. Несовпадение не стоит устранять ручной заменой hash на сумму любого найденного архива.

Что lock не фиксирует

Lock-файл provider не закрепляет версию самого CLI и не служит полноценным lock для удалённых модулей. Версию Terraform/OpenTofu задают отдельно, а источники модулей фиксируют подходящими version или ref. План также зависит от входных переменных и текущего состояния удалённых объектов.

Формат имени .terraform.lock.hcl используется в обоих продуктах, но адрес registry — часть идентичности provider. Переход между продуктами и registry требует проверить source, выбранную версию и checksums, а не считать одинаковое имя файла доказательством полной взаимозаменяемости. Механика описана для Terraform и OpenTofu.

Завершённое обновление выглядит как связанный набор: изменение диапазона при необходимости, проверенный diff lock, план на выбранной версии и рабочая установка в CI без модификации lock. Тогда повторяемость обеспечивается конкретными входами, а не надеждой, что init сегодня выберет тот же пакет.

Ещё по теме

• Sensitive скрывает вывод, но что остаётся в state Terraform и OpenTofu
• Terraform и OpenTofu хотят пересоздать ресурс: как разобраться с планом

Продолжить изучение

Хотите управлять инфраструктурой через код и понимать последствия изменений? Plan, state, модули и работа с существующими ресурсами — темы программы «Terraform и OpenTofu: инфраструктура как код».