依存関係ロックファイル

OpenTofuの設定は、自身のコードベース外部からの2種類の外部依存関係を参照する場合があります。

プロバイダー：OpenTofuのプラグインであり、様々な外部システムとの連携をサポートするためにOpenTofuを拡張します。
モジュール：OpenTofuの設定構造（OpenTofu言語で記述）のグループを再利用可能な抽象化に分割することを可能にします。

これらの依存関係タイプはどちらも、OpenTofu自体およびそれらに依存する設定とは独立して公開および更新できます。そのため、OpenTofuは、現在の設定と潜在的に互換性のある依存関係のバージョンと、現在使用するために選択されているバージョンを決定する必要があります。

設定自体に含まれるバージョン制約は、*潜在的に*互換性のある依存関係のバージョンを決定しますが、各依存関係の特定のバージョンを選択した後、OpenTofuは将来同じ決定を（デフォルトで）再び行うことができるように、*依存関係ロックファイル*にその決定を記録します。

現時点では、依存関係ロックファイルは*プロバイダー*の依存関係のみを追跡します。 OpenTofuはリモートモジュールのバージョン選択を記憶しないため、OpenTofuは常に指定されたバージョン制約を満たす最新の使用可能なモジュールバージョンを選択します。 *正確な*バージョン制約を使用して、OpenTofuが常に同じモジュールバージョンを選択するようにすることができます。

ロックファイルの場所

依存関係ロックファイルは、設定内の個々のモジュールではなく、設定全体に属するファイルです。そのため、OpenTofuを実行すると、OpenTofuは現在の作業ディレクトリにこのファイルを作成し、そこに存在することを期待します。このディレクトリには、設定のルートモジュールの.tfまたは.tofuファイルも含まれています。

ロックファイルは常に.terraform.lock.hclという名前で、これは作業ディレクトリの.terraformサブディレクトリにOpenTofuがキャッシュする様々なアイテムのロックファイルであることを示すことを意図しています。

OpenTofuは、tofu initコマンドを実行するたびに、依存関係ロックファイルを自動的に作成または更新します。設定自体への潜在的な変更について話し合うのと同じように、コードレビューを通じて外部依存関係への潜在的な変更について話し合うことができるように、このファイルをバージョン管理リポジトリに含める必要があります。

依存関係ロックファイルは、メインのOpenTofu言語と同じ低レベル構文を使用しますが、依存関係ロックファイル自体はOpenTofu言語設定ファイルではありません。その違いを示すために、接尾辞は.tfまたは.tofuではなく.hclが付いています。

依存関係のインストール動作

tofu initが設定に必要なすべてのプロバイダーのインストールに取り組んでいるとき、OpenTofuは設定のバージョン制約とロックファイルに記録されているバージョン選択の両方を考慮します。

特定のプロバイダーに既存の記録された選択がない場合、OpenTofuは指定されたバージョン制約に一致する最新の使用可能なバージョンを選択し、その選択を含むようにロックファイルを更新します。

特定のプロバイダーの選択が既にロックファイルに記録されている場合、OpenTofuは、新しいバージョンが利用可能になった場合でも、常にインストールのためにそのバージョンを再選択します。 tofu initを実行するときに-upgradeオプションを追加することで、この動作をオーバーライドできます。この場合、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はまた、インストールする各パッケージが、以前にロックファイルに記録されたチェックサム（存在する場合）の少なくとも1つと一致することを確認し、チェックサムが一致しない場合はエラーを返します。

コードブロック
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.

このチェックサム検証は、初回使用時信頼（Trust on First Use）のアプローチを体現することを目的としています。新しいプロバイダーを初めて追加する際に、任意の方法、または関連規制で要求される方法で検証できます。その後、OpenTofu は、将来のtofu initの実行で、同じプロバイダーバージョンに対して一致しないパッケージが検出された場合にエラーを発生させます。

「初回使用時信頼」モデルには、2 つの特別な考慮事項があります。

暗号署名付きチェックサムを提供するオリジンレジストリからプロバイダーをインストールする場合、OpenTofu は、1 つのチェックサムが一致する限り、すべての署名付きチェックサムを有効として扱います。したがって、ロックファイルには、現在のプラットフォーム用にインストールしたパッケージと、他のプラットフォームで利用可能な他のパッケージの両方のチェックサムが含まれます。

この場合、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",
   ]
 }

新しいプロバイダーバージョンを選択する主な効果は、providerブロックのversionの値を変更することです。アップグレードによって設定されたバージョン制約が変更された場合、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:` は、それぞれ異なるアルゴリズムを使用してチェックサムの計算を表す異なるハッシュスキームを表します。既存のスキームに制限があることが判明した場合、または新しいスキームがかなりの追加の利点をもたらす場合、新しいハッシュスキームを導入することがあります。

現在サポートされている2つのハッシュスキームは次のとおりです。

zh:: 「zip hash」のニーモニック。これは OpenTofu プロバイダーレジストリプロトコルの一部であるレガシーハッシュ形式であるため、オリジンレジストリから直接インストールするプロバイダーに使用されます。

このハッシュスキームは、オリジンレジストリにインデックス付けされた公式の.zipパッケージそれぞれの SHA256 ハッシュを取得します。これは、レジストリからインストールされた公式リリースパッケージを検証するための効果的なスキームですが、展開されたディレクトリレイアウトを使用するファイルシステムミラーなど、他のプロバイダーインストール方法からのパッケージの検証には適していません。
h1:: 現在の推奨ハッシュスキームである「ハッシュスキーム1」のニーモニック。

ハッシュスキーム1も SHA256 ハッシュですが、含まれている.zipアーカイブではなく、プロバイダー配布パッケージの*コンテンツ*から計算されます。したがって、このスキームには、公式の`.zip`ファイル、同じコンテンツの展開されたディレクトリ、または同じファイルを含むが、メタデータまたは圧縮スキームが異なる可能性のある再圧縮された`.zip`ファイルに対して計算できるという利点があります。

zh:スキームの適用範囲が限られているため、OpenTofu は、対応するh1:チェックサムを学習すると同時に追加します。これが、上記の変更例で 2 番目のh1:チェックサムが追加された原因です。

OpenTofu は、ハッシュが*既存のハッシュのいずれかとも一致する*パッケージから計算された場合にのみ、既存のプロバイダーに新しいハッシュを追加します。上記の例では、OpenTofu は元の `h1:` チェックサムを生成したものとは異なるプラットフォーム用に `hashicorp/azurerm` パッケージをインストールしましたが、以前に記録された `zh:` チェックサムのいずれかと一致させることができました。 `zh:` チェックサムの一致を確認した後、OpenTofu は古いスキームから新しいスキームに徐々に移行するために、対応する `h1:` チェックサムを記録しました。

特定のプロバイダーを初めてインストールする場合（既存のproviderブロックがない場合）、OpenTofu は、プロバイダー開発者の暗号署名でカバーされているチェックサムでhashes値を事前に設定します。これは通常、サポートされているすべてのプラットフォームでそのプロバイダーバージョンのすべての利用可能なパッケージをカバーします。ただし、プロバイダーレジストリプロトコルはまだ`zh:`スキームを使用しているため、初期セットは主にそのスキームを使用するハッシュで構成され、OpenTofu は異なるプラットフォームにパッケージをインストールするときに徐々にアップグレードします。

新しいターゲットプラットフォームで設定を操作するときに新しいh1:ハッシュが継続的に追加されるのを避けたい場合、またはミラーからプロバイダーをインストールしていて公式の署名付きチェックサムを提供できない場合は、tofu providers lockコマンドを使用して、選択したプラットフォームセットのハッシュを事前に設定するように OpenTofu に依頼できます。

コードブロック
tofu providers lock \
  -platform=linux_arm64 \
  -platform=linux_amd64 \
  -platform=darwin_amd64 \
  -platform=windows_amd64

上記のコマンドは、指定された 4 つのプラットフォームすべてで、必要なすべてのプロバイダーの公式パッケージをダウンロードして検証し、それぞれに `zh:` と `h1:` の両方のチェックサムをロックファイルに記録します。これにより、OpenTofu が後で `h1:` の同等物を学習するケースを回避できます。このコマンドの詳細については、`tofu providers lock` のドキュメントを参照してください。

不要になったプロバイダー

特定のプロバイダーへの依存関係がまだ存在するかどうかを判断するために、OpenTofu は 2 つの情報源を使用します。設定自体と状態です。設定と状態の両方から特定のプロバイダーへの最後の依存関係を削除すると、`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 はそれをまったく新しいプロバイダーであるかのように扱い、以前に選択されたのと同じバージョンを選択するとは限らず、チェックサムが変更されていないことを確認できません。

依存関係ロックファイル

ロックファイルの場所​

依存関係のインストール動作​

チェックサム検証​

ロックファイルの変更の理解​

新しいプロバイダーへの依存関係​

既存のプロバイダーの新しいバージョン​

新しいプロバイダーパッケージのチェックサム​

不要になったプロバイダー​