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

Конфигурация 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 всегда будет повторно выбирать эту версию для установки, даже если стала доступна более новая. Это поведение можно изменить, добавив параметр -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 будет считать все контрольные суммы действительными, если хотя бы одна из них совпадает с установленным пакетом. Поэтому файл блокировки будет содержать контрольные суммы как для пакета, установленного для вашей текущей платформы, так и для любых других пакетов, доступных для других платформ. Если вы хотите ограничить такое поведение только провайдерами, подписанными криптографической подписью, задайте для OPENTOFU_ENFORCE_GPG_VALIDATION значение true.

  Если имеется криптографическая подпись, вывод 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:: мнемоническое обозначение «hash scheme 1» (схема хеширования 1), предпочтительная на данный момент схема хеширования.

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

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

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

При первой установке определённого провайдера (когда для него ещё нет существующего блока provider) OpenTofu заранее заполнит значение hashes всеми контрольными суммами, предоставленными реестром. Обычно это охватывает все доступные пакеты этой версии провайдера для всех поддерживаемых платформ. Реестр OpenTofu (по состоянию на OpenTofu v1.12) предоставляет полный набор хешей zh (Zip Hash) и h1 (Hash Scheme 1).

Если вы хотите избежать постоянного добавления новых хешей 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 будет считать его совершенно новым провайдером. Поэтому он не обязательно выберет ту же версию, что и раньше, и не сможет проверить, остались ли контрольные суммы прежними.