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

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