名前付き値への参照

OpenTofuでは、いくつかの種類の名前付き値を使用できます。これらの名前はそれぞれ、関連付けられた値を参照する式です。これらはスタンドアロン式として使用することも、他の式と組み合わせて新しい値を計算することもできます。

名前付き値の種類

OpenTofuで使用できる主な種類の名前付き値は次のとおりです。

リソース
入力変数
ローカル値
子モジュールの出力
データソース
ファイルシステムとワークスペース情報
ブロックローカル値

以下のセクションでは、各種類の名前付き値について詳しく説明します。

これらの名前の多くは、オブジェクト値の要素の属性表記に似たドット区切りのパスを使用していますが、実際にはオブジェクトとして実装されていません。つまり、記述どおりに正確に使用する必要があります。角かっこ表記を使用してドット区切りのパスを置き換えることはできません。また、名前付きエンティティの「親オブジェクト」を反復処理することはできません。たとえば、aws_instanceをfor式で使用して、すべてのAWSインスタンスリソースを反復処理することはできません。

リソース

<RESOURCE TYPE>.<NAME>は、指定されたタイプと名前の管理対象リソースを表します。

リソース参照の値は、リソースがcountまたはfor_eachを使用しているかどうかによって異なります。

リソースがcountまたはfor_eachを使用していない場合、参照の値はオブジェクトです。リソースの属性はオブジェクトの要素であり、ドット表記または角かっこ表記を使用してアクセスできます。
リソースにcount引数が設定されている場合、参照の値は、そのインスタンスを表すオブジェクトの*リスト*です。
リソースにfor_each引数が設定されている場合、参照の値は、そのインスタンスを表すオブジェクトの*マップ*です。

以下にリストされている他のパターンと一致しない名前付き値は、OpenTofuによって管理対象リソースへの参照として解釈されます。

リソース参照の使用方法の詳細については、以下のリソース属性への参照を参照してください。

入力変数

var.<NAME>は、指定された名前の入力変数の値です。

変数に型制約（type引数）が宣言の一部として含まれている場合、OpenTofuは呼び出し元によって指定された値を型制約に準拠するように自動的に変換します。

そのため、var.を使用した参照は、呼び出し元が自動的に変換された異なる型の値を提供した場合でも、常に型制約に準拠する値を生成すると安全に想定できます。

特に、特定の属性を持つオブジェクト型として変数を定義した場合、呼び出し元が実際に追加の属性を持つ値を渡した場合でも、モジュールの他の場所では*それらの特定の属性*のみが使用可能になることに注意してください。モジュールの他の場所で使用 intended するすべての属性を型制約で定義する必要があります。

ローカル値

local.<NAME>は、指定された名前のローカル値の値です。

ローカル値は、循環依存関係を導入しない限り、同じlocalsブロック内でも他のローカル値を参照できます。

子モジュールの出力

module.<MODULE NAME>は、 `module`ブロックの結果を表す値です。

対応するmoduleブロックにcountもfor_eachも設定されていない場合、値は子モジュールで定義された各出力値に1つの属性を持つオブジェクトになります。モジュールの出力値の1つにアクセスするには、module.<MODULE NAME>.<OUTPUT NAME>を使用します。

対応するmoduleがfor_eachを使用する場合、値は、キーがfor_each式のキーに対応し、値がそれぞれ子モジュールで定義された各出力値に1つの属性を持つオブジェクトであるオブジェクトのマップになります。それぞれ1つのモジュールインスタンスを表します。

対応するモジュールが`count`を使用する場合、結果は`for_each`と似ていますが、値が要求された数の要素を持つ*リスト*である点が異なります。各要素は1つのモジュールインスタンスを表します。

データソース

data.<DATA TYPE>.<NAME>は、指定されたデータソースのタイプと名前のデータリソースを表すオブジェクトです。リソースにcount引数が設定されている場合、値はインスタンスを表すオブジェクトのリストです。リソースにfor_each引数が設定されている場合、値はインスタンスを表すオブジェクトのマップです。

詳細については、リソース属性への参照を参照してください。これは、参照がデータリソース用であることを示すために`data.`プレフィックスが追加されることを除いて、データリソースにも適用されます。

ファイルシステムとワークスペース情報

以下の値を使用できます。

path.module は、式が配置されているモジュールのファイルシステムパスです。リモートモジュールソースを使用するかローカルモジュールソースを使用するかによって動作が異なる可能性があるため、書き込み操作で path.module を使用することはお勧めしません。ローカルモジュールの複数回の呼び出しは同じソースディレクトリを使用するため、呼び出しごとに path.module のデータが上書きされます。これは、競合状態や予期しない結果につながる可能性があります。
path.root は、構成のルートモジュールのファイルシステムパスです。
path.cwd は、-chdir 引数を適用する前に OpenTofu を実行した元の作業ディレクトリのファイルシステムパスです。このパスは、ファイルシステム構造に関する詳細を含む絶対パスです。また、OpenTofu がルートモジュールディレクトリ以外のディレクトリから実行される高度なケースでも役立ちます。可能な場合は、path.cwd よりも path.root または path.module を使用することをお勧めします。
terraform.workspace は、現在選択されているワークスペースの名前です。

このセクションの値は、構成が適用されるコンテキストに関する情報を含むため、モジュールの移植性や構成可能性に悪影響を及ぼす可能性があるため、注意して使用してください。

たとえば、path.cwd を直接使用してリソース引数にパスを入力した場合、後で異なるディレクトリから、または異なるディレクトリ構造を持つ異なるコンピューターで同じ構成を適用すると、パスが同じファイルを指している場合でも、プロバイダーはパスの変更を適用する変更と見なします。

同様に、これらの値のいずれかを共有モジュールで名前空間の一種として使用する場合（たとえば、terraform.workspace をグローバルに一意のオブジェクト名のプレフィックスとして使用する場合）、同じ構成でモジュールを複数回呼び出すことができない場合があります。

path.module を除いて、このセクションの値は構成のルートモジュールでのみ使用することをお勧めします。一意の名前を作成するためにプレフィックスが必要な共有モジュールを作成する場合は、モジュールに input 変数を定義し、呼び出し元のモジュールがプレフィックスを定義できるようにします。呼び出し元のモジュールは、必要に応じて terraform.workspace を使用して定義するか、そうでない場合は他の値を使用できます。

コードブロック
module "example" {
  # ...

  name_prefix = "app-${terraform.workspace}"
}

ブロックローカル値

特定のブロックの本体内、またはその他の特定のコンテキストでは、上記にリストされているグローバル値以外にも、使用可能な名前付き値があります。これらのローカル名は、それらが表示される特定のコンテキストのドキュメントに記載されています。最も一般的なローカル名のいくつかは次のとおりです。

count メタ引数を使用するリソースの count.index。
for_each メタ引数を使用するリソースの each.key / each.value。
プロビジョナーおよび接続ブロックの self。

注記

ローカル名は、ドキュメントでは、多くの場合、*変数* または *一時変数* と呼ばれます。これらは入力変数ではありません。値を一時的に表す任意の名前です。

このセクションの名前は、トップレベルの構成ブロックにのみ関連しています。dynamic ブロックを使用して、resource および data ブロック内にリソースタイプ固有の *ネストされた* ブロックを動的に生成する場合、各要素のキーと値は異なる方法で参照します。詳細は、dynamic ブロックのドキュメントを参照してください。

名前付き値と依存関係

リソースやモジュール呼び出しなどのコンストラクトは、多くの場合、ブロック本体で名前付き値への参照を使用し、OpenTofu はこれらの式を分析して、オブジェクト間の依存関係を自動的に推測します。たとえば、別の管理対象リソースを参照するリソース引数の式は、2 つのリソース間に暗黙的な依存関係を作成します。

リソース属性への参照

最も一般的な参照タイプは、resource または data ブロックで宣言されたリソースの属性への参照です。このようなブロックの内容はそれ自体が非常に複雑になる可能性があるため、これらの内容を参照する式も複雑になる可能性があります。

次のリソースブロックの例を考えてみましょう。

コードブロック
resource "aws_instance" "example" {
  ami           = "ami-abc123"
  instance_type = "t2.micro"

  ebs_block_device {
    device_name = "sda2"
    volume_size = 16
  }
  ebs_block_device {
    device_name = "sda3"
    volume_size = 20
  }
}

aws_instance のドキュメントには、このリソースタイプでサポートされているすべての引数とネストされたブロックがリストされており、このリソースタイプによって *エクスポート* される多くの属性もリストされています。これらの異なるリソースタイプスキーマコンストラクトはすべて、次のように参照で使用できます。

構成で設定された ami 引数は、参照式 aws_instance.example.ami を使用して他の場所で使用できます。
このリソースタイプによってエクスポートされた id 属性は、同じ構文を使用して読み取ることができ、aws_instance.example.id になります。
ebs_block_device ネストされたブロックの引数は、splat 式を使用してアクセスできます。たとえば、すべての device_name 値のリストを取得するには、aws_instance.example.ebs_block_device[*].device_name を使用します。
この特定のリソースタイプのネストされたブロックには、エクスポートされた属性はありませんが、ebs_block_device にドキュメント化された id 属性がある場合、それらのリストは aws_instance.example.ebs_block_device[*].id と同様にアクセスできます。
ネストされたブロックは、各ブロックを識別するための論理キーを受け取るように定義されている場合があります。これは、式でその単一のブロックを参照するための便利な方法を提供することにより、リソース自体の名前と同様の役割を果たします。aws_instance に、そのようなキーを受け入れる仮説的なネストされたブロックタイプ device がある場合、構成では次のようになります。
コードブロック
```
  device "foo" {
    size = 2
  }
  device "bar" {
    size = 4
  }
```
*キー* を持つブロック内の引数は、aws_instance.example.device["foo"].size などのインデックス構文を使用してアクセスできます。

*ラベル付き* のネストされたブロックタイプの特定の引数の値のマップを取得するには、for 式を使用します：{for k, device in aws_instance.example.device : k => device.size}。

リソースに count 引数が設定されている場合、リソース自体は単一のオブジェクトではなく、インスタンスオブジェクトの *リスト* になります。その場合、splat 式またはインデックス構文を使用してインスタンスの属性にアクセスします。

aws_instance.example[*].id は、各インスタンスのすべての ID のリストを返します。
aws_instance.example[0].id は、最初のインスタンスの ID のみを返します。

リソースに for_each 引数が設定されている場合、リソース自体は単一のオブジェクトではなく、インスタンスオブジェクトの *マップ* になり、インスタンスの属性はキーで指定するか、for 式を使用してアクセスできます。

aws_instance.example["a"].id は、「a」キーのリソースの ID を返します。
[for value in aws_instance.example: value.id] は、各インスタンスのすべての ID のリストを返します。

count と異なり、splat 式は for_each で管理されるリソースに直接適用 *できない* ことに注意してください。splat 式はリスト値で動作する必要があるためです。ただし、values() 関数を使用してインスタンスをリストとして抽出し、そのリスト値を splat 式で使用できます。

values(aws_instance.example)[*].id

機密リソース属性

リソースタイプのスキーマを定義する場合、プロバイダー開発者は特定の属性を *機密* としてマークできます。その場合、OpenTofu は、その属性を含むプランをレンダリングするときに、実際の値の代わりにプレースホルダーマーカー (機密値) を表示します。

機密としてマークされたプロバイダー属性は、機密として宣言された入力変数と同様に動作します。OpenTofu はプランと適用メッセージで値を非表示にし、そこから派生した他の値も機密として非表示にします。ただし、OpenTofu が機密変数を公開する場合があるケースで説明されているように、その動作にはいくつかの制限があります。

リソース属性からの機密値を出力値の一部として使用する場合、OpenTofu は、エクスポートすることを意図していたことを確認するために、出力値自体も機密としてマークすることを要求します。

OpenTofu は、機密値を状態に記録するため、状態データにアクセスできる人は誰でも、クリアテキストで機密値にアクセスできます。詳細については、*状態の機密データ*を参照してください。

まだわかっていない値

OpenTofu が構成を適用する一連の変更を計画している場合、一部のリソース属性値は、リモートシステムによって値が動的に決定されるため、すぐに設定できません。たとえば、特定のリモートオブジェクトタイプに作成時に生成された一意の ID が割り当てられている場合、OpenTofu はオブジェクトが作成されるまでこの ID の値を予測できません。

OpenTofu は、計画段階で予測できない情報に対して、特別な不明な値のプレースホルダーを使用します。OpenTofu 言語は、式で不明な値を自動的に処理します。たとえば、既知の値に不明な値を追加すると、結果として不明な値が自動的に生成されます。

ただし、不明な値が *重要な* 影響を与える状況がいくつかあります。

リソースの count メタ引数は、作成するインスタンス数を決定するために計画フェーズ中に評価する必要があるため、不明値にすることはできません。
データリソースの構成で不明値が使用されている場合、そのデータリソースは計画フェーズ中に読み取ることができないため、適用フェーズまで延期されます。この場合、データリソースの結果も*不明値*になります。
不明値が module ブロック内の引数に割り当てられている場合、子モジュール内の対応する入力変数への参照はすべてその不明値を使用します。
不明値が出力値の value 引数で使用されている場合、親モジュール内のその出力値への参照はすべてその不明値を使用します。
OpenTofuは可能な限り不明値が適切な型であることを検証しようとしますが、そのような値の誤った使用は適用フェーズまで検出されない場合があり、適用の失敗を引き起こす可能性があります。

不明値は tofu plan の出力に (適用後に判明) として表示されます。

名前付き値への参照

名前付き値の種類​

リソース​

入力変数​

ローカル値​

子モジュールの出力​

データソース​

ファイルシステムとワークスペース情報​

ブロックローカル値​

名前付き値と依存関係​

リソース属性への参照​

機密リソース属性​

まだわかっていない値​