CLI構成ファイル (`.tofurc` または `tofu.rc`)

CLI構成ファイルは、すべてのOpenTofu作業ディレクトリに適用される、CLIの動作に関するユーザーごとの設定を構成します。これは、インフラストラクチャ構成とは異なります。

場所

構成は、ホストオペレーティングシステムによって場所が異なる単一のファイルに配置できます。

Windowsでは、ファイルの名前はtofu.rcにする必要があり、関連するユーザーの%APPDATA%ディレクトリに配置する必要があります。このディレクトリの物理的な場所は、Windowsのバージョンとシステム構成によって異なります。システム上の場所を確認するには、PowerShellで$env:APPDATAを使用します。terraform.rcは、下位互換性のためにサポートされています。terraform.rcファイルとtofu.rcファイルの両方が存在する場合、後者が優先されます。
その他のすべてのシステムでは、ファイルの名前は.tofurc（先頭にピリオドが付いていることに注意）にする必要があり、関連するユーザーのホームディレクトリに直接配置するか、tofurcという名前を付け、$XDG_CONFIG_HOME/opentofuなどの有効なXDG Base Directory構成ディレクトリに配置する必要があります。.terraformrcは、下位互換性のためにサポートされています。.terraformrcファイルと.tofurcファイルの両方が存在する場合、後者が優先されます。XDG構成ディレクトリを使用する場合、.terraformrcとterraformrcは無視されます。

Windowsでは、Windowsエクスプローラーのデフォルトの動作であるファイル名拡張子の非表示に注意してください。OpenTofuは、Windowsエクスプローラーで名前がtofu.rcと表示されていても、tofuc.rc.txtという名前のファイルをCLI構成ファイルとして認識しません。PowerShellまたはコマンドプロンプトからdirを使用してファイル名を確認してください。

OpenTofu CLI構成ファイルの場所は、TF_CLI_CONFIG_FILE環境変数を使用して指定することもできます。そのようなファイルは、*.tfrcという命名パターンに従う必要があります。

構成ファイルの構文

構成ファイルは、.tfファイルと.tofuファイルと同じHCL構文を使用しますが、属性とブロックが異なります。次の例は一般的な構文を示しています。これらの各設定の意味については、次のセクションを参照してください。

コードブロック
plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"

利用可能な設定

CLI構成ファイルでは、次の設定を行うことができます。

credentials - クラウドバックエンドで使用するための資格情報を構成します。詳細については、下記の資格情報を参照してください。
credentials_helper - クラウドバックエンド用の資格情報の保存と取得のための外部ヘルパープログラムを構成します。詳細については、下記の資格情報ヘルパーを参照してください。
plugin_cache_dir — プラグインキャッシュを有効にし、プラグインキャッシュディレクトリの場所を文字列として指定します。
provider_installation - プロバイダプラグインのインストール時にtofu initで使用されるインストール方法をカスタマイズします。詳細については、下記のプロバイダのインストールを参照してください。

資格情報

OpenTofu固有のネットワークサービスと対話する場合、OpenTofuはcredentialsブロック内のCLI構成ファイルにAPIトークンがあることを期待します。

コードブロック
credentials "app.opentofu.org" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

Webブラウザーを備えたコンピューターでOpenTofu CLIを対話的に実行している場合は、tofu loginコマンドを使用して資格情報を取得し、CLI構成に自動的に保存できます。そうでない場合は、credentialsブロックを手動で記述できます。

複数のホストのサービスを定期的に使用する場合は、複数のcredentialsブロックを持つことができます。各credentialsブロックには、そのホストで使用するAPIトークンを指定するtoken引数が含まれています。

注意

資格情報のホスト名は、モジュールソースまたはバックエンド構成のホスト名と一致する必要があります。

環境変数資格情報

APIトークンをCLI構成に直接保存したくない場合は、ホスト固有の環境変数を使用できます。環境変数名は、ドメイン名にTF_TOKEN_プレフィックスを追加する必要があります。ピリオドはアンダースコアとしてエンコードします。たとえば、TF_TOKEN_app_opentofu_orgという名前の変数の値は、CLIがホスト名app.opentofu.orgにサービスリクエストを行うときにベアラー認証トークンとして使用されます。

非ASCII文字を含むドメイン名は、punycode相当のACEプレフィックスに変換する必要があります。たとえば、例えば.comのトークン資格情報は、TF_TOKEN_xn--r8j3dr99h_comという変数に設定する必要があります。

ハイフンもホスト名内で有効ですが、通常は変数名として無効であり、二重アンダースコアとしてエンコードされる場合があります。たとえば、ドメイン名café.frのトークンは、TF_TOKEN_xn--caf-dma.fr、TF_TOKEN_xn--caf-dma_fr、またはTF_TOKEN_xn____caf__dma_frとして設定できます。複数の変数が同じホスト名に評価される場合、OpenTofuはオペレーティングシステムの変数テーブルで最後に定義されたものを選択します。

資格情報ヘルパー

credentials_helperを構成して、別の資格情報ストレージメカニズムを使用するようにOpenTofuに指示できます。

コードブロック
credentials_helper "example" {
  args = []
}

credentials_helper は、CLI構成ファイルに最大1回だけ記述できる構成ブロックです。そのラベル（上記の例では"example"）は、使用するクレデンシャルヘルパーの名前です。args 引数はオプションで、ヘルパープログラムに追加の引数を渡すことができます。例えば、クレデンシャルにアクセスするためにリモートホストのアドレスを設定する必要がある場合などに使用します。

構成されたクレデンシャルヘルパーは、前のセクションで説明したように、credentialsブロックで明示的に構成されていないホストのクレデンシャルを取得する場合にのみ参照されます。逆に、これはcredentials_helperブロックと並んでcredentialsブロックを記述することで、特定のホスト名に対してヘルパーから返されるクレデンシャルを上書きできることを意味します。

OpenTofuのメインディストリビューションには、クレデンシャルヘルパーは含まれていません。既存の社内クレデンシャル管理システムと連携するために、独自のクレデンシャルヘルパーを作成してインストールする方法については、クレデンシャルヘルパーの内部構造に関するガイドを参照してください。

クレデンシャルソースの優先順位

上記で説明したように、特定のサービスホストの環境変数で見つかったクレデンシャルは、tofu loginで設定されたCLI構成のクレデンシャルよりも優先されます。どちらも設定されていない場合は、構成済みのクレデンシャルヘルパーが参照されます。

プロバイダーのインストール

プロバイダープラグインをインストールするデフォルトの方法は、プロバイダーレジストリからです。プロバイダーの元のレジストリは、registry.opentofu.org/hashicorp/awsのようなプロバイダーのソースアドレスにエンコードされています。一般的なケースでは、便宜上、OpenTofuはregistry.opentofu.org上のプロバイダーのホスト名部分を省略できるため、hashicorp/awsのような短いパブリックプロバイダーアドレスを記述できます。

ただし、元のレジストリから直接プラグインをダウンロードすることが常に適切であるとは限りません。例えば、OpenTofuを実行しているシステムが、組織内またはローカルのファイアウォール制限のために元のレジストリにアクセスできない場合があります。

このような状況でOpenTofuプロバイダーを使用できるようにするために、OpenTofuでプロバイダープラグインを利用可能にするためのいくつかの代替オプションがあり、次のセクションで説明します。

明示的なインストール方法の設定

CLI構成のprovider_installationブロックを使用すると、OpenTofuのデフォルトのインストール動作を上書きして、OpenTofuが使用する予定のプロバイダーの一部またはすべてに対してローカルミラーを強制的に使用させることができます。

provider_installationブロックの一般的な構造は次のとおりです。

コードブロック
provider_installation {
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
}

provider_installationブロック内のネストされた各ブロックは、1つのインストール方法を指定します。各インストール方法は、特定のインストール方法で使用できるプロバイダーを指定するincludeとexcludeの両方のパターンを取ることができます。上記の例では、元のレジストリがexample.comにあるプロバイダーは、/usr/share/terraform/providersにあるファイルシステムミラーからのみインストールでき、他のすべてのプロバイダーは元のレジストリから直接インストールできると指定しています。

特定のインストール方法に対してincludeとexcludeの両方を設定した場合、除外パターンが優先されます。例えば、registry.opentofu.org/hashicorp/*を含めるが、registry.opentofu.org/hashicorp/dnsを除外すると、そのインストール方法はhashicorp/dnsを除いて、hashicorp名前空間のすべてのものに適用されます。

メイン構成のプロバイダーソースアドレスと同様に、ワイルドカードを使用する場合でも、パブリックOpenTofuレジストリを通じて配布されるプロバイダーの場合はregistry.opentofu.org/プレフィックスを省略できます。例えば、registry.opentofu.org/hashicorp/*とhashicorp/*は同等です。*/*は*/*/*ではなく、registry.opentofu.org/*/*の省略形です。

以下は、サポートされているインストール方法のタイプです。

direct：プロバイダーに関する情報を元のレジストリから直接要求し、そのレジストリが示す場所からネットワーク経由でダウンロードします。この方法は、追加の引数を必要としません。
filesystem_mirror：プロバイダーのコピーについてローカルディスク上のディレクトリを参照します。この方法は、どのディレクトリを検索するかを示す追加の引数pathが必要です。

OpenTofuは、指定されたディレクトリに、パスセグメントが利用可能なプロバイダーに関するメタデータを提供するネストされたディレクトリ構造が含まれていることを想定しています。次の2つのディレクトリ構造がサポートされています。
- パックされたレイアウト: HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zipは、プロバイダーの元のレジストリから取得された配布zipファイルです。
- アンパックされたレイアウト: HOSTNAME/NAMESPACE/TYPE/VERSION/TARGETは、プロバイダーの配布zipファイルを展開した結果を含むディレクトリです。
どちらのレイアウトでも、VERSIONは2.0.0のような文字列であり、TARGETはdarwin_amd64、linux_arm、windows_amd64などの形式を使用して特定のターゲットプラットフォームを指定します。

アンパックされたレイアウトを使用する場合、OpenTofuは、プロバイダーをインストールする際に、ディレクトリの深いコピーを作成するのではなく、ミラーディレクトリへのシンボリックリンクを作成しようとします。パックされたレイアウトでは、OpenTofuがインストール中にzipファイルを展開する必要があるため、これを防ぐことができます。

検索する複数の異なるディレクトリを指定するために、複数のfilesystem_mirrorブロックを含めることができます。
network_mirror: プロバイダーが属するレジストリホストに関係なく、プロバイダーのコピーについて特定のHTTPSサーバーを参照します。この方法は、ミラーベースURLを示す追加の引数urlが必要です。URLはhttps:スキームを使用し、末尾がスラッシュで終わる必要があります。

OpenTofuは、指定されたURLが、プロバイダーネットワークミラープロトコルの実装のベースURLであることを想定しています。これは、一般的な静的Webサイトホスティングメカニズムを使用して比較的簡単に実装できるように設計されています。

警告

信頼できないnetwork_mirror URLを設定しないでください。プロバイダーミラーサーバーは、身元を検証するためにTLS証明書チェックの対象となりますが、TLS証明書を持つネットワークミラーは、悪意のあるコンテンツを含む上流プロバイダーの変更されたコピーを提供する可能性があります。

OpenTofuは、指定されたすべての方法のうち、includeとexcludeのパターンが特定のプロバイダーに一致するものをすべて試行し、各OpenTofu構成に指定されたバージョン制約に一致する、それらのすべての方法で利用可能な最新バージョンを選択します。特定のプロバイダーのローカルミラーがあり、OpenTofuにそのローカルミラーのみを使用させる場合は、directインストール方法を完全に削除するか、そのexclude引数を使用して、特定のプロバイダーでの使用を無効にする必要があります。

暗黙的なローカルミラーディレクトリ

CLI構成にprovider_installationブロックがまったく含まれていない場合、OpenTofuは暗黙的な構成を生成します。暗黙的な構成には、filesystem_mirror方法の選択と、その後のdirect方法が含まれます。

OpenTofuがファイルシステムミラーとして選択できるディレクトリのセットは、OpenTofuを実行しているオペレーティングシステムによって異なります。

Windows: %APPDATA%/terraform.d/plugins および %APPDATA%/HashiCorp/Terraform/plugins
Mac OS X: $HOME/.terraform.d/plugins、~/Library/Application Support/io.terraform/plugins、および /Library/Application Support/io.terraform/plugins
Linuxおよびその他のUnix系システム: $HOME/.terraform.d/plugins および、$XDG_DATA_HOME/opentofu/pluginsなどの有効なXDG Base Directoryデータディレクトリ内にあるopentofu/plugins。

カレントワーキングディレクトリにterraform.d/pluginsディレクトリが存在する場合、OpenTofuはオペレーティングシステムに関係なく、そのディレクトリも含めます。この動作は、initコマンドで-chdirオプションを使用すると変更されます。その場合、OpenTofuは、-chdirで指定したディレクトリではなく、起動ディレクトリのterraform.d/pluginsディレクトリをチェックします。

OpenTofuは、上記の各パスをチェックして、存在するかどうかを確認し、存在する場合はファイルシステムミラーとして扱います。したがって、各内部のディレクトリ構造は、明示的なインストール方法の設定で説明したfilesystem_mirrorブロックの2つの構造のいずれかと一致する必要があります。

ゼロ個以上の暗黙的なfilesystem_mirrorブロックに加えて、OpenTofuは暗黙的なdirectブロックも作成します。OpenTofuは、すべてのファイルシステムミラーディレクトリをスキャンして、そこにどのプロバイダーが配置されているかを確認し、暗黙的なdirectブロックからそれらのすべてのプロバイダーを自動的に除外します。（この自動exclude動作は、暗黙的なdirectブロックにのみ適用されます。明示的なprovider_installationを使用する場合は、意図した除外を自分で記述する必要があります。）

プロバイダープラグインキャッシュ

デフォルトでは、tofu initは、各ワーキングディレクトリが自己完結型になるように、ワーキングディレクトリのサブディレクトリにプラグインをダウンロードします。その結果、同じプロバイダーを使用する複数の構成がある場合、構成ごとにそのプラグインの個別のコピーがダウンロードされます。

プロバイダープラグインは非常に大きい（数100メガバイト程度）場合があるため、このデフォルトの動作は、インターネット接続が遅いまたは従量制のユーザーにとっては不便な場合があります。したがって、OpenTofuはオプションでローカルディレクトリを共有プラグインキャッシュとして使用できるようにし、これにより、個別のプラグインバイナリを一度だけダウンロードできます。

プラグインキャッシュを有効にするには、CLI構成ファイルのplugin_cache_dir設定を使用します。例:

コードブロック
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

OpenTofuがプラグインをキャッシュする前に、このディレクトリが既に存在する必要があります。OpenTofuはディレクトリ自体を作成しません。

Windowsでは、構成ファイルパーサーがバックスラッシュをエスケープシーケンスの開始とみなすため、従来のバックスラッシュ（\）ではなく、フォワードスラッシュ区切り文字（/）を使用する必要があることに注意してください。

構成ファイルでこれを設定するのが、永続的な設定の推奨される方法です。あるいは、TF_PLUGIN_CACHE_DIR環境変数を使用して、キャッシュを有効にしたり、特定のシェルセッション内で既存のキャッシュディレクトリを上書きしたりできます。

export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"

プラグインキャッシュディレクトリが有効になっている場合、tofu init コマンドは、どのプラグインが利用可能かに関するメタデータを取得するために、設定済みまたは暗黙的なインストール方法を引き続き使用しますが、適切なバージョンが選択されると、まず選択されたプラグインがキャッシュディレクトリに既にあるかどうかを確認します。もしあれば、OpenTofuは以前にダウンロードしたコピーを使用します。

選択されたプラグインがキャッシュにまだない場合、OpenTofuはまずキャッシュにダウンロードし、そこから現在の作業ディレクトリ下の正しい場所にコピーします。可能な場合、OpenTofuはシンボリックリンクを使用して、キャッシュされたプラグインの別のコピーを複数のディレクトリに保存することを回避します。

プラグインキャッシュディレクトリは、同じディレクトリで操作する場合にキャッシュ管理ロジックとファイルシステムミラーロジックが競合するため、設定済みまたは暗黙的なファイルシステムミラーディレクトリの1つであってはなりません。

OpenTofuは、プラグインがプラグインキャッシュに配置されると、そこからプラグインを削除することはありません。時間の経過とともに、プラグインがアップグレードされると、キャッシュディレクトリには手動で削除する必要のある未使用のバージョンがいくつか含まれるようになる可能性があります。

注意

プラグインキャッシュディレクトリは、並行処理の安全性が保証されていません。複数の tofu init 呼び出しがある環境でのプロバイダーインストーラーの動作は未定義です。

プロバイダープラグインキャッシュが依存関係ロックファイルを壊すことを許可する

注記

ここで説明するオプションは、まれで例外的な状況のみを対象としています。本当に必要であり、有効にすることの影響を完全に理解している場合を除き、このオプションを設定しないでください。

デフォルトでは、OpenTofuは、そのプロバイダーの依存関係ロックファイルに記録されている少なくとも1つのチェックサムと一致する場合にのみ、グローバルキャッシュディレクトリのパッケージを使用します。これにより、OpenTofuは、特定の構成で新しいプロバイダーを初めて使用するときに、常に完全で正しい依存関係ロックファイルのエントリを生成できるようになります。

ただし、一部の特別な状況では、チームが意図したとおりに依存関係ロックファイルを使用できず、推奨どおりにバージョン管理に含めず、代わりにOpenTofuがプロバイダーをインストールするたびに再生成させていることがわかっています。

実行間でバージョン管理システムに依存関係ロックファイルを保持しないチーム向けに、OpenTofuは追加のCLI構成設定を許可しています。この設定では、依存関係ロックファイルにそれを確認するためのエントリがまだない場合でも、キャッシュディレクトリ内のパッケージを常に有効として扱うようにOpenTofuに指示します。

コードブロック
plugin_cache_may_break_dependency_lock_file = true

または、環境変数 TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE を空文字列または 0 以外の任意の値に設定することもできます。これは、上記の設定と同等です。

このオプションを設定すると、OpenTofu CLIは、プロバイダーをインストールするためにキャッシュを使用できる場合、そのプロバイダーの不完全な依存関係ロックファイルエントリを作成する許可を与えます。その状況では、依存関係ロックファイルは現在のシステムで使用するには有効ですが、グローバルキャッシュのパッケージのチェックサムのみが含まれるため、オペレーティングシステムやCPUアーキテクチャが異なる別のコンピューターで使用するには有効でない可能性があります。

ほとんどのユーザーは、このオプションを設定しないままにすることをお勧めします。その場合、OpenTofuは、特定の構成で初めて使用するときは常にアップストリームからプロバイダーをインストールしますが、依存関係ロックファイルがプロバイダーパッケージの有効なチェックサムを記録すると、後の実行でキャッシュエントリを再利用できます。

注記

OpenTofuチームは、将来のバージョンで依存関係ロックファイルのメカニズムを改善し、より多くの状況で使用できるようにする予定です。その時点で、このオプションは黙って無視されるようになります。ワークフローがこのオプションの使用に依存している場合は、依存関係ロックファイルを壊さずにそれをサポートする方法を検討できるように、状況の詳細を共有するためにGitHub issueを開いてください。

プロバイダー開発者向けの開発オーバーライド

通常、OpenTofuは、すべての操作が意図したバージョンのプロバイダーで行われることを保証し、作者が制御された方法で新しいプロバイダーバージョンに段階的にアップグレードできるようにするために、プロバイダーのバージョン選択とチェックサムを検証します。

ただし、これらのバージョンとチェックサムのルールは、プロバイダーを開発するときには不便です。多くの場合、まだバージョン番号が関連付けられておらず、プロバイダーレジストリにリストされている公式のチェックサムのセットもないプロバイダーの開発ビルドに対してテスト構成を試したいからです。

プロバイダー開発の便宜上、OpenTofuは、provider_installation ブロックに特別な追加ブロック dev_overrides をサポートしています。このブロックの内容は、他のすべての設定済みインストール方法を事実上オーバーライドするため、このタイプのブロックは常にシーケンスの最初に表示される必要があります。

コードブロック
provider_installation {

  # Use /home/developer/tmp/terraform-null as an overridden package directory
  # for the hashicorp/null provider. This disables the version and checksum
  # verifications for this provider and forces OpenTofu to look for the
  # null provider plugin in the given directory.
  dev_overrides {
    "hashicorp/null" = "/home/developer/tmp/terraform-null"
  }

  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, OpenTofu will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}

開発オーバーライドが有効になっている場合、tofu init コマンドは、インストールして将来使用するために依存関係ロックファイルに記録するための、適切な公開バージョンのプロバイダーを選択しようとしますが、tofu apply などの他のコマンドは、hashicorp/null のロックファイルのエントリを無視し、代わりに指定されたディレクトリを使用します。新しい変更がプロバイダーの公開リリースに含まれたら、tofu init -upgrade を使用して、依存関係ロックファイルで新しいバージョンを選択し、開発オーバーライドを削除できます。

特定のプロバイダーのオーバーライドパスは、プロバイダーを配布するときに .zip ファイルに含まれるものと同様のディレクトリである必要があります。少なくとも、terraform-provider-null のようなプレフィックスが付いた実行可能ファイルが含まれます。ここで、null はプロバイダータイプです。プロバイダーが配布パッケージ内の他のファイルを使用する場合は、それらのファイルもオーバーライドディレクトリにコピーできます。

プロバイダー開発を積極的に行っているシェルセッションでのみ開発オーバーライドを有効にすることができます。その場合は、上記のコンテンツのようなローカルCLI構成ファイルを開発ディレクトリに記述し（たとえば、便宜上 dev.tfrc と呼びます）、次に TF_CLI_CONFIG_FILE 環境変数を使用して、OpenTofuにデフォルトのCLI構成の代わりにローカライズされたCLI構成を使用するように指示できます。

export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc

開発オーバーライドは、OpenTofuにローカルファイルシステムでプロバイダーを探させる一般的な方法としての使用は意図されていません。リリース済みプロバイダーのコピーをローカルファイルシステムに配置したい場合は、代わりに暗黙的なローカルミラーディレクトリまたは明示的なインストール方法の構成を参照してください。

この開発オーバーライドメカニズムは、よりスムーズなプロバイダー開発を可能にするための実用的な方法として意図されています。その動作、構成方法、および依存関係ロックファイルとの相互作用に関する詳細は、将来のOpenTofuリリースで変更される可能性があり、破壊的な変更が含まれる場合もあります。したがって、プロバイダー開発作業中にのみ、一時的に開発オーバーライドを使用することをお勧めします。

CLI構成ファイル (.tofurc または tofu.rc)

場所​

構成ファイルの構文​

利用可能な設定​

資格情報​

環境変数資格情報​

資格情報ヘルパー​

クレデンシャルソースの優先順位​

プロバイダーのインストール​

明示的なインストール方法の設定​

暗黙的なローカルミラーディレクトリ​

プロバイダープラグインキャッシュ​

プロバイダープラグインキャッシュが依存関係ロックファイルを壊すことを許可する​

プロバイダー開発者向けの開発オーバーライド​