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

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

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

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

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

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

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