コマンド: plan

tofu plan コマンドは、実行計画を作成します。これにより、OpenTofu がインフラストラクチャに対して行う予定の変更をプレビューできます。デフォルトでは、OpenTofu が計画を作成する際、以下の処理が行われます。

• 既に存在するリモートオブジェクトの現在の状態を読み取り、OpenTofu ステートが最新であることを確認します。
• 現在の構成を以前のステートと比較し、相違点を記録します。
• 適用された場合、リモートオブジェクトを構成に一致させる変更アクションのセットを提案します。

plan コマンド自体は、提案された変更を実際には実行しません。このコマンドを使用して、変更を適用する前に提案された変更が期待どおりであるかを確認したり、チームと変更を共有してより広範なレビューを行ったりできます。

OpenTofu がリソースインスタンスまたはルートモジュール出力値に変更が必要ないと検出した場合、tofu plan はアクションを実行する必要がないと報告します。

インタラクティブターミナルで OpenTofu を直接使用しており、OpenTofu が提案する変更を適用する場合は、代わりに tofu apply を直接実行できます。デフォルトでは、"apply" コマンドは新しい計画を自動的に生成し、承認を求めるプロンプトを表示します。

オプションの -out=FILE オプションを使用して、生成された計画をディスク上のファイルに保存できます。後でこのファイルを tofu apply に追加の引数として渡すことで実行できます。この 2 段階のワークフローは、主に OpenTofu を自動化で実行する場合を想定しています。

-out=FILE オプションなしで tofu plan を実行すると、投機的計画が作成されます。これは、計画の効果を説明するものであり、実際に適用する意図はありません。

実際のインフラストラクチャへの変更にバージョン管理とコードレビューのワークフローを使用するチームでは、開発者は投機的計画を使用して、コードレビューに提出する前に変更の影響を確認できます。ただし、その間にターゲットシステムに加えられた他の変更により、構成変更の最終的な影響が以前の投機的計画が示したものとは異なる可能性があることを考慮することが重要です。したがって、適用する前に、最終的な投機的でない計画を必ず再確認して、意図と一致していることを確認する必要があります。

使い方​

使い方: tofu plan [オプション]

plan サブコマンドは、現在の作業ディレクトリでルートモジュール構成を検索します。

plan コマンドは OpenTofu の主要なコマンドの 1 つであるため、次のセクションで説明するようにさまざまなオプションがあります。ただし、OpenTofu の構成は通常、特別な追加オプションなしで動作するように設計されている必要があるため、ほとんどの場合、これらのオプションを設定する必要はありません。

このページの残りのセクションでは、さまざまなオプションについて説明します。

• 計画モード: リモートシステムを構成に一致させるだけでなく、特殊な状況で使用できるいくつかの特別な代替計画モードがあります。
• 計画オプション: 特別な計画モードに加えて、異常なニーズに対応するために計画プロセスをカスタマイズするために設定できるオプションもいくつかあります。
  • リソースターゲティングは、いくつかの重要な注意点に関連付けられている特別な計画オプションの 1 つです。
• その他のオプション: これらは、生成された計画の内容をカスタマイズするのではなく、計画コマンド自体の動作を変更します。

計画モード​

前のセクションでは、OpenTofu のデフォルトの計画動作について説明しました。これは、構成に加えた変更に合わせてリモートシステムを変更します。OpenTofu には、それぞれ異なる意図された結果を持つ計画を作成する 2 つの代替計画モードがあります。これらのオプションは、tofu plan と tofu apply の両方で使用できます。

• 破棄モード: 現在存在するすべてのリモートオブジェクトを破棄し、空の OpenTofu ステートを残すことを目的とする計画を作成します。これは、tofu destroy の実行と同じです。破棄モードは、開発タスクが完了すると管理対象オブジェクトが役に立たなくなる一時的な開発環境などの状況に役立ちます。

  -destroy コマンドラインオプションを使用して、破棄モードをアクティブにします。

• リフレッシュ専用モード: OpenTofu の外部でリモートオブジェクトに加えられた変更に一致するように、OpenTofu ステートとルートモジュール出力値を更新することのみを目的とする計画を作成します。これは、通常ワークフローの外で 1 つ以上のリモートオブジェクトを意図的に変更した場合 (インシデントへの対応中など) で、これらの変更と OpenTofu の記録を調整する必要がある場合に役立ちます。

  -refresh-only コマンドラインオプションを使用して、リフレッシュ専用モードを有効にします。

OpenTofu が代替モードが選択されていない場合にデフォルトで使用するプランニングモードについて議論する必要がある場合、「通常モード」と呼びます。これらの代替モードは特殊な状況でのみ使用されるため、OpenTofu の他のドキュメントでは通常モードのプランニングのみを説明している場合があります。

プランニングモードはすべて相互排他的であるため、デフォルト以外のプランニングモードを有効にすると「通常」プランニングモードが無効になり、複数の代替モードを同時に使用することはできません。

プランニングオプション​

代替のプランニングモードに加えて、プランニングの動作を変更できるいくつかのオプションがあります。これらのオプションは tofu plan と tofu apply の両方で使用できます。

• -refresh=false - 設定の変更を確認する前に、OpenTofu の状態とリモートオブジェクトを同期するデフォルトの動作を無効にします。これにより、リモート API リクエストの数を減らすことで、プランニング操作を高速化できます。ただし、refresh=false を設定すると、OpenTofu は外部の変更を無視するため、不完全または不正確なプランになる可能性があります。リフレッシュ専用プランニングモードでは refresh=false を使用できません。これはプランニング操作全体を事実上無効にするためです。

• -replace=ADDRESS - 指定されたアドレスのリソースインスタンスを置き換えるプランを作成するように OpenTofu に指示します。これは、1 つ以上のリモートオブジェクトが劣化した場合に役立ち、同じ構成の置き換えオブジェクトを使用して、イミュータブルインフラストラクチャパターンに合わせることができます。OpenTofu は、指定されたリソースが通常「更新」アクションまたはアクションなしになる場合に、「置換」アクションを使用します。このオプションを複数回含めて、複数のオブジェクトを一度に置換します。-replace は -destroy オプションと併用できません。

• -target=ADDRESS - 指定されたアドレスに一致するリソースインスタンスと、それらのインスタンスが依存するオブジェクトのみにプランニングを集中するように OpenTofu に指示します。

  注

  -target=ADDRESS は、間違いからの回復や OpenTofu の制限事項の回避など、例外的な状況でのみ使用してください。詳細については、リソースターゲティングを参照してください。

• -var 'NAME=VALUE' - 設定のルートモジュールで宣言された単一の入力変数の値を設定します。このオプションを複数回使用して、複数の変数を設定します。詳細については、コマンドラインでの入力変数を参照してください。

• -var-file=FILENAME - 「tfvars」ファイルからの定義を使用して、設定のルートモジュールで宣言された、多数の入力変数の値を設定します。このオプションを複数回使用して、複数のファイルからの値を含めます。

ルートモジュールで入力変数の値を設定するには、-var および -var-file オプション以外にもいくつかの方法があります。詳細については、ルートモジュール変数への値の割り当てを参照してください。

コマンドラインでの入力変数​

-var コマンドラインオプションを使用して、ルートモジュールで宣言された入力変数の値を指定できます。

ただし、そのためには、選択したコマンドラインシェル *と* OpenTofu の両方で解析可能なコマンドラインを作成する必要があります。これは、多くの引用符とエスケープシーケンスを含む式の場合、複雑になる可能性があります。ほとんどの場合、代わりに -var-file オプションを使用し、実際の値を別のファイルに書き込んで、OpenTofu がシェルの解析結果を解釈するのではなく、直接解析できるようにすることをお勧めします。

Linux や macOS などのシステム上の Unix スタイルのシェルで -var を使用するには、シェルが値を文字通り解釈するように、オプション引数を一重引用符 ' で囲むことをお勧めします。

tofu plan -var 'name=value'

目的の値に一重引用符も含まれる場合は、シェルで正しく解釈されるようにエスケープする必要があります。そのためには、バックスラッシュエスケープ文字が有効になるように、引用符で囲まれたシーケンスを一時的に終了する必要もあります。

tofu plan -var 'name=va'\''lue'

Windows で OpenTofu を使用する場合は、Windows コマンドプロンプト (cmd.exe) を使用することをお勧めします。Windows コマンドプロンプトから OpenTofu に変数の値を渡す場合は、引数を二重引用符 " で囲みます。

tofu plan -var "name=value"

目的の値にリテラルの二重引用符が含まれる場合は、バックスラッシュでエスケープする必要があります。

tofu plan -var "name=va\"lue"

Windows の PowerShell は、リテラルの引用符を外部プログラムに正しく渡すことができないため、Windows で PowerShell を使用して OpenTofu を使用することはお勧めしません。代わりに、Windows コマンドプロンプトを使用してください。

変数値を記述するための適切な構文は、変数の型制約によって異なります。プリミティブ型 string、number、および bool はすべて、上記の例に示すように、シェルで必要な特殊な句読点を除いて、特別な句読点のない直接的な文字列値を期待します。リスト、マップ、およびセットタイプ、および特殊な any キーワードを含むその他のすべての型制約については、値を表す有効な OpenTofu 言語式を記述し、シェルで OpenTofu に文字通り渡されるように、必要な引用符またはエスケープ文字を記述する必要があります。たとえば、list(string) 型制約の場合

# Unix-style shell
tofu plan -var 'name=["a", "b", "c"]'

# Windows Command Prompt (do not use PowerShell on Windows)
tofu plan -var "name=[\"a\", \"b\", \"c\"]"

同様の制約が、環境変数を使用して入力変数を設定する場合にも適用されます。ルートモジュール入力変数を設定するためのさまざまな方法の詳細については、ルートモジュール変数への値の割り当てを参照してください。

リソースターゲティング​

-target オプションを使用して、OpenTofu の注意をリソースのサブセットのみに集中させることができます。リソースアドレス構文を使用して、制約を指定できます。OpenTofu はリソースアドレスを次のように解釈します

• 指定されたアドレスが 1 つの特定のリソースインスタンスを識別する場合、OpenTofu はそのインスタンスのみを選択します。count または for_each が設定されたリソースの場合、リソースインスタンスアドレスには aws_instance.example[0] のように、インスタンスインデックス部分を含める必要があります。

• 指定されたアドレスがリソース全体を識別する場合、OpenTofu はそのリソースのすべてのインスタンスを選択します。count または for_each が設定されたリソースの場合、これはそのリソースに現在関連付けられている *すべて* のインスタンスインデックスを選択することを意味します。単一インスタンスリソース (count または for_each のいずれもなし) の場合、リソースアドレスとリソースインスタンスアドレスは同一であるため、この可能性は適用されません。

• 指定されたアドレスがモジュールインスタンス全体を識別する場合、OpenTofu はそのモジュールインスタンスとすべての子モジュールインスタンスに属するすべてのリソースのすべてのインスタンスを選択します。

OpenTofu が直接ターゲットにした 1 つ以上のリソースインスタンスを選択すると、それらの選択が直接的または間接的に依存する他のすべてのオブジェクトを含むように選択を拡張します。

このターゲティング機能は、間違いからの回復や OpenTofu の制限事項の回避など、例外的な状況のために提供されています。構成のドリフトが検出されずに、リソースの真の状態と構成との関係について混乱が生じる可能性があるため、ルーチン操作に -target を使用することは *お勧めしません*。

-target を非常に大きな構成の分離された部分を操作する手段として使用する代わりに、大きな構成をそれぞれ独立して適用できるいくつかの小さな構成に分割することを優先してください。データソースを使用すると、他の構成で作成されたリソースに関する情報にアクセスできるため、複雑なシステムアーキテクチャを独立して更新できる、より管理しやすい部分に分割できます。

その他のオプション​

tofu plan コマンドには、OpenTofu が作成するプランの種類をカスタマイズするのではなく、プランニングコマンドの入出力に関連する他のいくつかのオプションもあります。これらのコマンドは、そのコマンドのドキュメントに特に記載されていない限り、必ずしも tofu apply でも使用できるとは限りません。

利用可能なオプションは次のとおりです

• -compact-warnings - エラーが少なくとも 1 つ伴う場合を除き、要約メッセージのみを含むコンパクトな形式で警告メッセージを表示します。エラーのコンテキストとして警告テキストが役立つ可能性があるためです。

• -detailed-exitcode - コマンドが終了したときに詳細な終了コードを返します。この引数が指定されている場合、終了コードとその意味が変更され、結果のプランに含まれている内容に関するより詳細な情報が提供されます

  • 0 = 空の差分 (変更なし) で成功
  • 1 = エラー
  • 2 = 空ではない差分 (変更あり) で成功

• -generate-config-out=PATH - (実験的) 設定に import ブロックが存在する場合、OpenTofu はまだ存在しないインポートされたリソースの HCL を生成するように指示します。設定は、PATH にある新しいファイルに書き込まれます。PATH はまだ存在しない必要があります。存在する場合、OpenTofu はエラーを返します。計画が別の理由で失敗した場合でも、OpenTofu は設定の書き込みを試みる場合があります。

• -input=false - 値がまだ割り当てられていないルートモジュール入力変数の入力を促す OpenTofu のデフォルトの動作を無効にします。このオプションは、非対話型の自動化システムで OpenTofu を実行する場合に特に役立ちます。

• -json - 機械可読な JSON UI 出力を有効にします。これは -input=false を意味するため、設定には続行するために割り当てられていない変数の値があってはなりません。

• -lock=false - 操作中に状態ロックを保持しません。他のユーザーが同じワークスペースに対してコマンドを同時に実行する可能性がある場合、これは危険です。

• -lock-timeout=DURATION - -lock=false でロックが無効にされていない限り、OpenTofu にエラーを返す前に一定期間ロックの取得を再試行するように指示します。期間の構文は、数字と時間単位の文字 (例: 3 秒の場合は "3s") で構成されます。

• -no-color - 出力のターミナル書式設定シーケンスを無効にします。ターミナルの書式設定を解釈できないシステムで出力が表示されるコンテキストで OpenTofu を実行する場合は、これを使用します。

• -concise - 計画の出力を簡潔な方法で表示します。リフレッシュのログ行の表示をスキップします。

• -out=FILENAME - 生成された計画を、指定されたファイル名に不透明なファイル形式で書き込みます。これは、後で tofu apply に渡して計画された変更を実行したり、保存された計画ファイルを操作できる他の OpenTofu コマンドに渡したりできます。

  OpenTofu では、計画ファイルのファイル名に任意の名前を使用できますが、一般的な規則では tfplan という名前を付けます。OpenTofu が別のファイル形式として認識するサフィックスをファイルに付けないでください。.tf または .tofu サフィックスを使用すると、OpenTofu はファイルを構成ソースファイルとして解釈しようとするため、後続のコマンドで構文エラーが発生します。

  生成されたファイルは、他のソフトウェアでの使用を目的とした標準形式ではありませんが、ファイルには、完全な構成、計画された変更に関連付けられたすべての値、および入力変数を含むすべての計画オプションが含まれています。計画に機密データが含まれている場合、OpenTofu のターミナル出力で隠されている場合でも、計画ファイルにクリアテキストで保存されます。したがって、保存された計画ファイルは、潜在的に機密性の高いアーティファクトとして扱う必要があります。

• -parallelism=n - OpenTofu がグラフを走査する際の同時操作数を制限します。デフォルトは 10 です。

local バックエンドを使用する構成の場合のみ、tofu plan は従来のコマンドラインオプション -state を受け入れます。

異なる構成ディレクトリの指定​

ワークフローがルートモジュールディレクトリのオーバーライドに依存している場合は、代わりに -chdir グローバルオプションを使用してください。このオプションはすべてのコマンドで機能し、OpenTofu が現在の作業ディレクトリで通常読み書きするすべてのファイルを、指定されたディレクトリで一貫して検索するようにします。