Файл блокировки зависимостей

Конфигурация OpenTofu может ссылаться на два разных типа внешних зависимостей, которые находятся за пределами собственной кодовой базы:

• Провайдеры — плагины для OpenTofu, которые расширяют его возможности, позволяя взаимодействовать с различными внешними системами.
• Модули — позволяют выделять группы конструкций конфигурации OpenTofu (написанных на языке OpenTofu) в повторно используемые абстракции.

Оба этих типа зависимостей могут публиковаться и обновляться независимо от самого OpenTofu и от конфигураций, которые от них зависят. Поэтому OpenTofu должен определять, какие версии этих зависимостей потенциально совместимы с текущей конфигурацией и какие версии выбраны для использования в данный момент.

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

В настоящее время файл блокировки зависимостей отслеживает только зависимости типа провайдер. OpenTofu не запоминает выбранные версии удалённых модулей, поэтому всегда выбирает самую новую доступную версию модуля, которая соответствует указанным ограничениям версий. Чтобы OpenTofu всегда выбирал одну и ту же версию модуля, можно использовать точное ограничение версии.

Расположение файла блокировки​

Файл блокировки зависимостей относится ко всей конфигурации в целом, а не к каждому отдельному модулю в конфигурации. Поэтому OpenTofu создаёт его и ожидает найти в текущем рабочем каталоге при запуске OpenTofu. В этом же каталоге находятся файлы .tf или .tofu корневого модуля конфигурации.

Файл блокировки всегда называется .terraform.lock.hcl. Это имя призвано показать, что файл содержит блокировки различных элементов, кэшируемых OpenTofu в подкаталоге .terraform рабочего каталога.

OpenTofu автоматически создаёт или обновляет файл блокировки зависимостей при каждом запуске команды tofu init. Следует включить этот файл в репозиторий системы контроля версий, чтобы можно было обсуждать потенциальные изменения внешних зависимостей в ходе проверки кода, так же как и потенциальные изменения самой конфигурации.

В файле блокировки зависимостей используется тот же низкоуровневый синтаксис, что и в основном языке OpenTofu, однако сам файл блокировки не является файлом конфигурации на языке OpenTofu. Чтобы обозначить это отличие, его имя заканчивается суффиксом .hcl, а не .tf или .tofu.

Поведение при установке зависимостей​

При установке всех необходимых для конфигурации провайдеров с помощью tofu init OpenTofu учитывает и ограничения версий в конфигурации, и выбранные версии, записанные в файле блокировки.

Если для какого-либо провайдера ещё не записан выбор версии, OpenTofu выберет самую новую доступную версию, соответствующую заданному ограничению версии, а затем обновит файл блокировки, добавив в него этот выбор.

Если выбор версии для провайдера уже записан в файле блокировки, OpenTofu всегда будет повторно выбирать эту версию для установки, даже если стала доступна более новая версия. Это поведение можно переопределить, добавив параметр -upgrade при запуске tofu init. В этом случае OpenTofu проигнорирует существующие варианты выбора и снова выберет самую новую доступную версию, соответствующую ограничению версии.

Если вызов tofu init вносит изменения в файл блокировки, OpenTofu сообщит об этом в выводе:

OpenTofu has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

Увидев это сообщение, вы можете использовать свою систему контроля версий, чтобы проверить предложенные OpenTofu изменения файла. Если эти изменения соответствуют вашим намерениям, их можно отправить на обычную для вашей команды проверку кода.

Проверка контрольных сумм​

OpenTofu также проверяет, что каждый устанавливаемый пакет соответствует хотя бы одной из ранее записанных в файле блокировки контрольных сумм, если таковые имеются. Если ни одна контрольная сумма не совпадает, возвращается ошибка:

Error: Failed to install provider

Error while installing hashicorp/azurerm v2.1.0: the current package for
registry.opentofu.org/hashicorp/azurerm 2.1.0 doesn't match any of the
checksums previously recorded in the dependency lock file.

Такая проверка контрольных сумм реализует подход доверия при первом использовании. При первом добавлении нового провайдера его можно проверить любым выбранным вами способом или способом, предписанным соответствующими нормативными требованиями, а затем положиться на то, что OpenTofu сообщит об ошибке, если при последующем запуске tofu init обнаружит пакет для той же версии провайдера, контрольная сумма которого не совпадает.

При использовании модели «доверия при первом использовании» необходимо учитывать два особых момента:

• Если вы устанавливаете провайдер из исходного реестра, предоставляющего контрольные суммы с криптографической подписью, OpenTofu считает действительными все подписанные контрольные суммы, если совпадает хотя бы одна из них. Поэтому в файл блокировки будут включены контрольные суммы как для пакета, установленного для текущей платформы, так и для всех остальных пакетов, доступных для других платформ.

  В этом случае вывод tofu init будет содержать отпечаток ключа, которым подписаны контрольные суммы, и сообщение вида (signed, key ID 0C0AF313E5FD9F80). Прежде чем фиксировать файл блокировки с подписанными контрольными суммами, вы можете убедиться, что доверяете владельцу указанного ключа, либо загрузить и проверить полный набор доступных пакетов для данной версии провайдера.

• Если вы впервые устанавливаете провайдер альтернативным способом, например из файлового или сетевого зеркала, OpenTofu не сможет проверить контрольные суммы для платформ, отличных от той, на которой была запущена команда tofu init. Поэтому контрольные суммы для других платформ записаны не будут, и конфигурацию нельзя будет использовать на других платформах.

  Чтобы избежать этой проблемы, можно заранее добавить в файл блокировки контрольные суммы для нескольких платформ с помощью команды tofu providers lock. После этого последующие вызовы tofu init смогут проверять, соответствуют ли пакеты из выбранного вами зеркала официальным пакетам из исходного реестра провайдера.

Как понимать изменения файла блокировки​

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

OpenTofu может вносить в файл блокировки несколько разных типов изменений. Чтобы проверить предложенные изменения, может потребоваться разобраться в их значении. В следующих разделах описаны типичные случаи.

Зависимость от нового провайдера​

Если вы добавите новую запись в требования к провайдерам любого модуля конфигурации или добавите внешний модуль, у которого есть новая зависимость от провайдера, tofu init в ответ выберет самую новую версию этого провайдера, удовлетворяющую всем ограничениям версий в конфигурации, и запишет принятое решение в новый блок provider файла блокировки зависимостей.

--- .terraform.lock.hcl	2020-10-07 16:12:07.539570634 -0700
+++ .terraform.lock.hcl	2020-10-07 16:12:15.267487237 -0700
@@ -6,6 +6,26 @@
   ]
 }

+provider "registry.opentofu.org/hashicorp/azurerm" {
+  version     = "2.30.0"
+  constraints = "~> 2.12"
+  hashes = [
+    "h1:FJwsuowaG5CIdZ0WQyFZH9r6kIJeRKts9+GcRsTz1+Y=",
+    "h1:c/ntSXrDYM1mUir2KufijYebPcwKqS9CRGd3duDSGfY=",
+    "h1:yre4Ph76g9H84MbuhZ2z5MuldjSA4FsrX6538O7PCcY=",
+    "zh:04f0a50bb2ba92f3bea6f0a9e549ace5a4c13ef0cbb6975494cac0ef7d4acb43",
+    "zh:2082e12548ebcdd6fd73580e83f626ed4ed13f8cdfd51205d8696ffe54f30734",
+    "zh:246bcc449e9a92679fb30f3c0a77f05513886565e2dcc66b16c4486f51533064",
+    "zh:24de3930625ac9014594d79bfa42d600eca65e9022b9668b54bfd0d924e21d14",
+    "zh:2a22893a576ff6f268d9bf81cf4a56406f7ba79f77826f6df51ee787f6d2840a",
+    "zh:2b27485e19c2aaa9f15f29c4cff46154a9720647610171e30fc6c18ddc42ec28",
+    "zh:435f24ce1fb2b63f7f02aa3c84ac29c5757cd29ec4d297ed0618423387fe7bd4",
+    "zh:7d99725923de5240ff8b34b5510569aa4ebdc0bdb27b7bac2aa911a8037a3893",
+    "zh:7e3b5d0af3b7411dd9dc65ec9ab6caee8c191aee0fa7f20fc4f51716e67f50c0",
+    "zh:da0af4552bef5a29b88f6a0718253f3bf71ce471c959816eb7602b0dadb469ca",
+  ]
+}
+
 provider "registry.opentofu.org/newrelic/newrelic" {
   version     = "2.1.2"
   constraints = "~> 2.1.1"

Новая запись в файле блокировки содержит несколько сведений:

• version: точная версия, выбранная OpenTofu с учётом ограничений версий в конфигурации.
• constraints: все ограничения версий, учтённые OpenTofu при выборе. (OpenTofu не использует эти сведения непосредственно при принятии решений об установке, но включает их, чтобы помочь читателям понять, как было принято предыдущее решение.)
• hashes: несколько контрольных сумм, которые считаются действительными для пакетов с выбранной версией этого провайдера на разных платформах. Подробнее о значении этих хешей рассказано ниже в разделе Новые контрольные суммы пакетов провайдера.

Новая версия существующего провайдера​

Если запустить tofu init -upgrade и попросить OpenTofu рассмотреть более новые версии провайдера, которые по-прежнему соответствуют настроенным ограничениям версий, OpenTofu может выбрать для провайдера более новую версию и обновить существующий блок provider, отразив это изменение.

--- .terraform.lock.hcl	2020-10-07 16:44:25.819579509 -0700
+++ .terraform.lock.hcl	2020-10-07 16:43:42.785665945 -0700
@@ -7,22 +7,22 @@
 }

 provider "registry.opentofu.org/hashicorp/azurerm" {
-  version     = "2.1.0"
-  constraints = "~> 2.1.0"
+  version     = "2.0.0"
+  constraints = "2.0.0"
   hashes      = [
-    "h1:EOJImaEaVThWasdqnJjfYc6/P8N/MRAq1J7avx5ZbV4=",
-    "zh:0015b491cf9151235e57e35ea6b89381098e61bd923f56dffc86026d58748880",
-    "zh:4c5682ba1e0fc7e2e602d3f103af1638f868c31fe80cc1a884a97f6dad6e1c11",
-    "zh:57bac885b108c91ade4a41590062309c832c9ab6bf6a68046161636fcaef1499",
-    "zh:5810d48f574c0e363c969b3f45276369c8f0a35b34d6202fdfceb7b85b3ac597",
-    "zh:5c6e37a44462b8662cf9bdd29ce30523712a45c27c5d4711738705be0785db41",
-    "zh:64548940a3387aa3a752e709ee9eb9982fa820fe60eb60e5f212cc1d2c58549e",
-    "zh:7f46749163da17330bbb5293dc825333c86304baa0a7c6256650ac536b4567c8",
-    "zh:8f8970f2df75ac43ffdd112055ee069d8bd1030f7eb4367cc4cf494a1fa802c3",
-    "zh:9ad693d00dc5d7d455d06faba70e716bce727c6706f7293288e87fd7956b8fe0",
-    "zh:b6e3cb55e6aec62b47edd0d2bd5e14bd6a2bcfdac65930a6e9e819934734c57b",
-    "zh:d6a3f3b9b05c28ecf3919e9e7afa185805a6d7442fc4b3eedba749c2731d1f0e",
-    "zh:d81fb624a357c57c7ea457ce543d865b39b12f26c2edd58a2f7cd43326c91010",
+    "h1:bigGXBoRbp7dv79bEEn+aaju8575qEXHQ57XHVPJeB8=",
+    "zh:09c603c8904ca4a5bc19e82335afbc2837dcc4bee81e395f9daccef2f2cba1c8",
+    "zh:194a919d4836d6c6d4ce598d0c66cce00ddc0d0b5c40d01bb32789964d818b42",
+    "zh:1f269627df4e266c4e0ef9ee2486534caa3c8bea91a201feda4bca525005aa0a",
+    "zh:2bae3071bd5f8e553355c4b3a547d6efe1774a828142b762e9a4e85f79be7f63",
+    "zh:6c98dfa5c3468e8d02e2b3af7c4a8a14a5d469ce5a642909643b413a17ca338b",
+    "zh:7af78f61666fd45fbf428161c061ea2623162d601b79dc71d6a5158756853ffa",
+    "zh:883c2df86ae9ba2a5c167cf5c2c7deca0239171a224d6d335f0fd6dd9c283830",
+    "zh:a2028379078577d8ff5ecfca6e8a8b25a25ffb1686de0ee52a7fe8011783488b",
+    "zh:abe6ef399552fd3861a454a839cd978c1d15735658fdc00f9054435aff0f4620",
+    "zh:c30b1bf14077913c3cdf34979b1434dbb1353cb5995eb3956b191c50538b64a9",
+    "zh:ca64ae2ad9793e5631e3b0b9327f7cb22cb5d8e9de57be7d85821791b1d5a375",
+    "zh:fffe56904a38109bb8d613b02808a177c3ddfac19f03b3aac799281fea38f475",
   ]
 }

Основное последствие выбора новой версии провайдера — изменение значения version в блоке provider. Если обновление сопровождалось изменением настроенных ограничений версий, OpenTofu также запишет это изменение в значение constraints.

Поскольку для каждой версии предусмотрен собственный набор дистрибутивных пакетов, при переходе на новую версию обычно также заменяются все значения в hashes, чтобы отразить контрольные суммы пакетов новой версии.

Новые контрольные суммы пакетов провайдера​

Менее очевидное изменение, которое можно увидеть в блоке provider, — добавление новых контрольных сумм, отсутствовавших ранее, даже если остальные данные в блоке provider не изменились:

--- .terraform.lock.hcl	2020-10-07 17:24:23.397892140 -0700
+++ .terraform.lock.hcl	2020-10-07 17:24:57.423130253 -0700
@@ -10,6 +10,7 @@
   version     = "2.1.0"
   constraints = "~> 2.1.0"
   hashes = [
+    "h1:1xvaS5D8B8t6J6XmXxX8spo97tAzjhacjedFX1B47Fk=",
     "h1:EOJImaEaVThWasdqnJjfYc6/P8N/MRAq1J7avx5ZbV4=",
     "zh:0015b491cf9151235e57e35ea6b89381098e61bd923f56dffc86026d58748880",
     "zh:4c5682ba1e0fc7e2e602d3f103af1638f868c31fe80cc1a884a97f6dad6e1c11",

Добавление новой контрольной суммы в значение hashes означает, что OpenTofu постепенно переходит между разными схемами хеширования. Префиксы h1: и zh: у этих значений обозначают разные схемы хеширования, каждая из которых подразумевает вычисление контрольной суммы с помощью отдельного алгоритма. Время от времени мы можем вводить новые схемы хеширования, если обнаружим ограничения существующих схем или если новая схема даст значительные дополнительные преимущества.

В настоящее время поддерживаются две схемы хеширования:

• zh:: мнемоническое обозначение «zip hash» (хеш ZIP), устаревший формат хеша, входящий в протокол реестра провайдеров OpenTofu. Поэтому он используется для провайдеров, устанавливаемых непосредственно из исходного реестра.

  Эта схема хеширования сохраняет хеш SHA256 для каждого официального пакета .zip, зарегистрированного в исходном реестре. Она эффективно подходит для проверки официальных релизных пакетов, устанавливаемых из реестра, но не подходит для проверки пакетов из других способов установки провайдеров, например из файловых зеркал, использующих структуру каталогов с распакованными пакетами.

• h1:: мнемоническое обозначение «схема хеширования 1» — предпочтительная на данный момент схема хеширования.

  Схема хеширования 1 также использует хеш SHA256, но вычисляет его по содержимому дистрибутивного пакета провайдера, а не по архиву .zip, в котором он содержится. Поэтому эту схему можно использовать для официального файла .zip, распакованного каталога с тем же содержимым или заново сжатого файла .zip с теми же файлами, но потенциально другими метаданными или способом сжатия.

  Из-за ограниченной области применения схемы zh: OpenTofu будет по возможности добавлять соответствующие контрольные суммы h1: по мере того, как будет узнавать о них. Именно поэтому в примере изменения выше появилась вторая контрольная сумма h1:.

OpenTofu добавляет новый хеш для существующего провайдера только в том случае, если он вычислен по пакету, который также соответствует одному из существующих хешей. В приведённом выше примере OpenTofu установил пакет hashicorp/azurerm для платформы, отличной от той, для которой была получена исходная контрольная сумма h1:, но смог сопоставить его с одной из ранее записанных контрольных сумм zh:. Убедившись в совпадении контрольной суммы zh:, OpenTofu записал соответствующую контрольную сумму h1:, чтобы постепенно перейти от старой схемы к новой.

При первой установке конкретного провайдера (когда для него ещё нет блока provider) OpenTofu заранее заполняет значение hashes всеми контрольными суммами, покрываемыми криптографической подписью разработчика провайдера. Обычно подпись охватывает все доступные пакеты этой версии провайдера для всех поддерживаемых платформ. Однако, поскольку в протоколе реестра провайдеров по-прежнему используется схема zh:, изначально набор будет состоять преимущественно из хешей этой схемы. Затем OpenTofu будет по возможности обновлять его по мере установки пакетов на разных платформах.

Если вы хотите избежать постоянного добавления новых хешей h1: при работе с конфигурацией на новых целевых платформах или устанавливаете провайдеры из зеркала, которое не может предоставлять официальные подписанные контрольные суммы, попросите OpenTofu заранее добавить хеши для выбранного набора платформ с помощью команды tofu providers lock:

tofu providers lock \
  -platform=linux_arm64 \
  -platform=linux_amd64 \
  -platform=darwin_amd64 \
  -platform=windows_amd64

Приведённая выше команда загрузит и проверит официальные пакеты всех необходимых провайдеров для всех четырёх указанных платформ, а затем запишет в файл блокировки контрольные суммы обоих типов — zh: и h1:. Это позволит избежать ситуации, когда OpenTofu узнает об эквиваленте h1: лишь позднее. Дополнительные сведения об этой команде см. в документации tofu providers lock.

Провайдеры, которые больше не требуются​

Чтобы определить, сохраняется ли зависимость от определённого провайдера, OpenTofu использует два источника достоверных сведений: саму конфигурацию и состояние. Если вы удалите последнюю зависимость от какого-либо провайдера и из конфигурации, и из состояния, tofu init удалит существующую запись этого провайдера из файла блокировки.

--- .terraform.lock.hcl	2020-10-07 16:12:07.539570634 -0700
+++ .terraform.lock.hcl	2020-10-07 16:12:15.267487237 -0700
@@ -6,26 +6,6 @@
   ]
 }

-provider "registry.opentofu.org/hashicorp/azurerm" {
-  version     = "2.30.0"
-  constraints = "~> 2.12"
-  hashes = [
-    "h1:FJwsuowaG5CIdZ0WQyFZH9r6kIJeRKts9+GcRsTz1+Y=",
-    "h1:c/ntSXrDYM1mUir2KufijYebPcwKqS9CRGd3duDSGfY=",
-    "h1:yre4Ph76g9H84MbuhZ2z5MuldjSA4FsrX6538O7PCcY=",
-    "zh:04f0a50bb2ba92f3bea6f0a9e549ace5a4c13ef0cbb6975494cac0ef7d4acb43",
-    "zh:2082e12548ebcdd6fd73580e83f626ed4ed13f8cdfd51205d8696ffe54f30734",
-    "zh:246bcc449e9a92679fb30f3c0a77f05513886565e2dcc66b16c4486f51533064",
-    "zh:24de3930625ac9014594d79bfa42d600eca65e9022b9668b54bfd0d924e21d14",
-    "zh:2a22893a576ff6f268d9bf81cf4a56406f7ba79f77826f6df51ee787f6d2840a",
-    "zh:2b27485e19c2aaa9f15f29c4cff46154a9720647610171e30fc6c18ddc42ec28",
-    "zh:435f24ce1fb2b63f7f02aa3c84ac29c5757cd29ec4d297ed0618423387fe7bd4",
-    "zh:7d99725923de5240ff8b34b5510569aa4ebdc0bdb27b7bac2aa911a8037a3893",
-    "zh:7e3b5d0af3b7411dd9dc65ec9ab6caee8c191aee0fa7f20fc4f51716e67f50c0",
-    "zh:da0af4552bef5a29b88f6a0718253f3bf71ce471c959816eb7602b0dadb469ca",
-  ]
-}
-
 provider "registry.opentofu.org/newrelic/newrelic" {
   version     = "2.1.2"
   constraints = "~> 2.1.1"

Если позднее вы добавите новое требование для того же провайдера и снова запустите tofu init, OpenTofu будет считать его совершенно новым провайдером. Поэтому он не обязательно выберет ту же версию, что и ранее, и не сможет проверить, остались ли контрольные суммы неизменными.