Terraform Provider
terraform プロバイダーは、Aggrega の Recipes を Terraform 設定にレンダリングします。このプロバイダーは設定を出力するだけで、Terraform を実行することはありません。Aggrega のビルドは事前(ahead-of-time)コンパイルであるため、terraform apply の後にしか存在しないリソース ID、IP アドレス、出力を解決できません。Terraform の ${ ... } 補間は、後で Terraform ランタイムが解決する決定的なポインター文字列として、そのまま素通しされます。このプロバイダーはオフラインかつハーメチックであり、ネットワークにアクセスすることも、terraform や tofu を呼び出すこともありません。
境界のレイアウト
terraform プロバイダは、境界内のコンポーネントを並べて出力するのではなく、境界を合成します。レンダリングする各境界には 1 つのルート構成 aggrega.modules.tf が作られ、そこでレンダリングされる各コンポーネントを module ブロックとして宣言します。その source は modules/ 配下にあるそのコンポーネント自身のサブディレクトリです。
module "cache" { source = "./modules/cache"}
module "db" { source = "./modules/db"
allocated_storage = 100 db_name = "appdb" engine_version = "11.4"}各コンポーネント自身のファイル(ベンダリングされたモジュールまたは記述された本体、および来歴スタンプ)は、そのブロックが指すサブディレクトリに置かれます。これは Terraform 標準の「ルートが子を合成する」構造であり、その慣例ではネストされたモジュールは modules/ サブディレクトリ配下に置かれます。コンポーネントが 1 つでも複数でも、すべての terraform 境界がこのレイアウトになります。コンポーネントまたは境界にアタッチされた Feature は、同じルート構成内でそれ自身の module ブロックとして宣言されます。アタッチされた Feature の出力の配置先を参照してください。
この形は見た目のためではなく、2 つの理由から構造上不可欠です。
Terraform の依存グラフは構成ごとに存在します。 別々のディレクトリに出力された Components は互いに関係のない別々のグラフになります。参照も depends_on も一方から他方へは届かず、単一の terraform plan が両方を参照することもありません。1 つのルートが各 component を子モジュールとして構成することで、boundary 全体が 1 つのグラフと 1 つのプランに収まります。
コンポーネントのファイルはそれ自身のディレクトリでアドレス指定されます。 1 つの境界内の 2 つのコンポーネントが、同名のファイル(main.tf、variables.tf)を書き出すモジュールをベンダリングすることがありますが、それぞれのファイル群は各コンポーネントのディレクトリ配下に置かれ、1 つのパスを奪い合うことはありません。
プロバイダの設定場所
プロバイダの設定(provider ブロック)はルートに書かれ、コンポーネントのモジュール内には決して書かれません。Terraform のドキュメントによれば、他から呼び出されることを意図したモジュールは provider ブロックを含んではならず、呼び出されたモジュールは、そのモジュールが使う各プロバイダについてルートのデフォルト設定を継承します。独自の provider ブロックを持つモジュールは depends_on、count、for_each 付きで呼び出せません。そしてこのプロバイダは、後述の「デプロイの順序」で説明するとおり、同じルートの別のコンポーネントがより早い syncWave を持つ場合には必ずコンポーネントの module ブロックに depends_on を書き込みます。その場合 Terraform は、何かをプランする前の読み込み時点で構成全体を拒否します。
そのため、プロバイダの設定が必要な Recipe は、その設定を spec.boundary.artifacts 配下のファイルとして書きます。そのようなファイルはそれぞれ aggrega.modules.tf の隣に一度だけ書き出され、Terraform はそれをルート構成と一緒に読み込みます。コンポーネントのモジュールには、プロバイダのソースとバージョンを示す required_providers 宣言だけが残ります。
infra/terraform/ aggrega.modules.tf provider-azurerm.tf modules/ gateway/main.tf1 つのルートに属する Components のうち、同じファイルを同じバイト列で宣言するものは 1 つのコピーを共有します。同じ名前で異なるバイト列の場合はビルドが停止します。モジュールのリソースはその 1 つの構成に紐づけて記録されるため、Terraform がそれらを破棄する際にもこの構成が使われます。そのファイルを宣言する最後の component を削除する Release は、ファイルも一緒に削除します。その結果、Terraform はそれらのモジュールが作成したものの破棄をプランすることを拒否し、provider を構成する provider ブロックを要求します。そのような最後の component を削除する前に、それらのリソースを破棄してください。
コンポーネントの入力の供給場所
コンポーネントの入力は、ルート構成内のその module ブロックの引数であり、入力が書かれるのはそこだけです。コンパイラがモジュールの入力を供給する場合、つまり source: でモジュールをベンダリングする Recipe の場合、ブロックは引数を持ちます。Recipe が構成本体を自ら記述し、値をその本体内に解決した場合、コンパイラが渡すものは何も残らないため、ブロックは引数を持ちません。
モジュール引数は Terraform が評価する位置であり、それが値をそこに置く理由です。Recipe が供給する ${ ... } ポインタは、リテラル文字列としてモジュールに届くのではなく、そこで解決されます。何に対して解決されるかといえば、それはルート構成です。参照はその構成が宣言するもの、つまり module.<name>.<output> の形でその module ブロックの 1 つを指し、宣言されていないものへの参照は、欠けている参照先を示すプラン時の明示的なエラーになります。
したがって、コンポーネント自身のディレクトリは、デプロイされるとおりにプランできる構成ではありません。 その入力は 1 つ上の階層であるルートに記述されているため、modules/<component> でエンジンを実行すると別のものがプランされます。どちらの結果になるかは、モジュール自身の variable ブロックによって決まります。
defaultを宣言していない入力が 1 つでもある場合、プランは明示的に失敗します。No value for required variableが未設定の各変数とその行を示し、Terraform 自身の-var/-var-fileによる対処法を提示します。- すべての入力が
defaultを持つ場合、プランは成功し、ルート構成が供給する値ではなくモジュールのデフォルト値から構築されます。警告は何も出ないため、これこそ知っておくべきケースです。正しく見えるプランが、誰も求めていない構成を記述しているのです。
代わりに、境界自身の出力ディレクトリ、つまり aggrega.modules.tf を含み modules/ のすぐ上にあるディレクトリをプランしてください。そこにデプロイの値があり、単一のプランで境界全体を見られる唯一の場所です。
他のコンポーネントが公開する値の利用
uses エッジで別のコンポーネントに接続されたコンポーネントは、自身の .context.inject パイプ(または .context.uses.<alias>.provides.<name>)を通じて、そのコンポーネントが公開する値を読み取ります。読み取るのはコンパイラが解釈せずにパイプする文字列であり、その文字列の行き先は、Recipe が書き込んだスコープで Terraform が評価するテキストです。terraform 境界にはそのようなスコープが 2 つあり、コンポーネント間参照に必要なモジュール呼び出しを宣言しているのはそのうち 1 つだけです。
- ルート構成はすべての寄与者を
moduleブロックとして宣言するため、そこではmodule.<name>.<output>が解決されます。 - コンポーネント自身のディレクトリはモジュール呼び出しをまったく宣言しないため、そこでは
module.<name>.<output>は何も指しません。<name>が何であっても同じです。正しい名前に置き換えても何も変わりません。欠けているのは綴りではなく宣言だからです。
したがって、利用された参照が解決できるかどうかを決めるのは、利用する側の Recipe の入力の種類であり、利用される値ではありません。
利用する側の Recipe は source: Recipe として記述してください。 その valuesMapping: は、ルート構成内にあるそれ自身の module ブロックの引数になります。これは評価され、かつ隣接するものが宣言されたスコープにある唯一の位置です。
具体例
提供側は自身のモジュール呼び出しを指すアドレスを公開します。これは利用側のスコープが宣言している形です。.context.instance_id は provides の評価対象で利用でき、デプロイの Aggregate が宣言するコンポーネントについては、そのコンポーネントの module ブロックが持つ名前になります。
# Recipe — the producer. Its vendored module declares `output "endpoint"`.spec: capability: terraform implements: example/storage/object-store:1.0.0 source: ./module valuesMapping: | bucket: "{{ .values.bucket }}" provides: endpoint: "${module.{{ .context.instance_id }}.endpoint}"利用側は入力を宣言するモジュールをベンダリングし、注入された値をそれにマッピングします。
# Recipe — the consumer. Its vendored module declares `variable "store_endpoint"`.spec: capability: terraform implements: example/compute/reporting-api:1.0.0 source: ./module valuesMapping: | store_endpoint: "{{ .context.inject.env.STORE_ENDPOINT }}"Aggregate はそれらを接続し、エッジが運ぶ公開キーを指定します。
spec: components: store: type: example/storage/object-store values: bucket: app-artifacts
api: type: example/compute/reporting-api uses: store: store: target: store inject: env: - in: STORE_ENDPOINT from: endpointビルドは、参照とその参照先が一緒に宣言された 1 つのルート構成を出力します。
module "api" { source = "./modules/api"
store_endpoint = "${module.store.endpoint}"}
module "store" { source = "./modules/store"
bucket = "app-artifacts"}同じ構成が module "store" を宣言しているため Terraform は module.store.endpoint を解決し、その値は通常の入力として利用側のモジュールに届きます。
aws-rds-and-ecs-service の例では、標準ライブラリの Recipes からこの組み合わせを構築します。公開されている RDS モジュールでプロビジョニングされる PostgreSQL データベースと、Amazon ECS 上で実行されるサーバーです。サーバーの environment 引数は、module "db" を宣言するルート構成内で ${module.db.db_instance_address} を持ちます。
うまくいかない 3 つのケースと、それぞれの現れ方
自身の本体を記述する Recipe は、コンポーネント間の参照を消費できません。 artifacts: Recipe は値を自身が書く本体の中で解決し、その本体はコンポーネント自身のディレクトリに出力されます。そのため参照は、モジュール呼び出しを一切宣言しないスコープに置かれることになります。
Error: Reference to undeclared module on modules/api/main.tf line 11, in output "seen": 11: value = "${module.store.endpoint}"No module call named "store" is declared in module.api.綴りを変えても解決しません。ネストされたモジュールの式は兄弟モジュールをまったく名指しできないためです。ネストされたモジュールが隣接するモジュールの値を受け取れるのは 入力 としてのみであり、それはソース指定のパスがすでに供給している module ブロックの引数です。別のコンポーネントが公開する値を消費するコンポーネントは、source: Recipe として記述します。
プロデューサー自身のモジュール内部を名指すアドレスは、そのモジュールではなくルートに対して解決されます。 aws_db_instance.this.endpoint と綴る provides エントリは、プロデューサーのモジュールが宣言するリソースを名指します。補間として書かれると、コンシューマーの引数が置かれる場所、つまりルートで評価されます。
Error: Reference to undeclared resource on aggrega.modules.tf line 19, in module "api": 19: store_endpoint = "${aws_db_instance.this.endpoint}"There is no managed resource "aws_db_instance" "this" definition in the root module.リソースの内部に手を伸ばすのではなく、${module.<...>.<output>} を公開し、その値のための output ブロックをモジュールに用意してください。
補間を含まない provides エントリはテキストとして渡されます。 これは失敗しないケースです。コンパイラは文字列を受け渡すだけでポインタとリテラルを区別できないため、${ ... } なしで書かれた aws_db_instance.this.endpoint は引用符付きの文字列としてレンダリングされ、ビルドは成功し、エンジンの検証も通り、コンシューマーは aws_db_instance.this.endpoint という文字列を受け取ります。値を参照として意図する場合は、必ず ${ ... } で囲んでください。これが、その文字列を Terraform が評価すべきものとして示します。
頼る前に知っておくべき 1 つの制約
.context.instance_id はコンポーネントの識別子を表し、module ブロックの名前はコンポーネントのファイルが置かれるディレクトリから導出されます。デプロイメント自身の Aggregate が宣言するコンポーネントでは、この 2 つは同じ名前になります。 別の Aggregate から合成されたコンポーネントではそうなりません。合成された識別子とモジュール名はそれぞれの文字体系に異なる形で書き込まれるため、参照は黙って失敗するのではなく、ルートで明示的なエラーになります。
Error: Reference to undeclared module on aggrega.modules.tf line 25, in module "api": 25: store_endpoint = "${module.nested-zdinner.endpoint}"No module call named "nested-zdinner" is declared in the root module.別のコンポーネントがアドレスを解決するプロデューサーは、それを消費するコンポーネントと並べて、デプロイメント自身の Aggregate で宣言してください。
アタッチされた Feature の出力の配置先
独自の設定をレンダリングする Feature のアタッチメントには 専用のモジュール が与えられ、隣接するコンポーネントと同じルート設定の中で宣言されます。これによって初めて、その設定がデプロイメントの一部になります。Terraform はディレクトリの直下にあるファイルだけを読み込み、ネストされたディレクトリは明示的に呼び出す必要のある完全に別のモジュールとして扱うため、アタッチメントのファイルが読み込まれるのは、ルートがそのディレクトリを名指すブロックを宣言しているからです。
アタッチメントのモジュールディレクトリはコンポーネントのディレクトリの 隣、modules/ の 1 階層下に置かれ、それを識別する 2 つの要素、すなわちホストするコンポーネントとアタッチ時の名前を -- で連結した名前が付けられます。したがって、aux という名前のアタッチメントを持つコンポーネント api の場合、ルート設定は 2 つのモジュールを宣言します。
module "api--aux" { source = "./modules/api--aux"}
module "api" { source = "./modules/api"}コンポーネントではなく 境界 にアタッチされた Feature には名指すべきホストコンポーネントがないため、ディレクトリ名はその名前のみになります。コンポーネント api を持つ境界上の aux という名前のアタッチメントは、./modules/api の隣に ./modules/aux を生成します。
内側ではなく隣に置く理由。 Terraform はモジュールディレクトリ内のトップレベルのファイルをすべて 1 つの名前空間に統合します。output、variable、resource、locals のいずれも同様です。そのため、ディレクトリを共有する 2 つのコントリビューターは、ファイル名にかかわらず、双方が宣言する名前で衝突します。それぞれにディレクトリを分けることで両者が分離されます。内側ではなく隣に置くことは、ネストされたモジュールに関する Terraform 自身のガイダンスが求めるものでもあります。すなわち、モジュール同士が直接呼び出し合って深くネストしたモジュールのツリーを作るのではなく、呼び出し側が合成できるようにすることです。
連結は座標ごとにエスケープされます。 2 つの座標はそれぞれ連結の前にディレクトリ用の文字体系に書き換えられるため、-- を含む座標が連結と混同されることはありません。a--b という名前のホストとアタッチメント c の組み合わせは、ホスト a とアタッチメント b--c の組み合わせと区別できます。大文字・小文字の ASCII 英字、数字、ピリオド、アンダースコアはそのまま通過し、記述したハイフンは直後の文字がそれらのいずれかであれば保持され、それ以外はエスケープされます。同じ規則と同じ文字体系がチャートターゲットの子ディレクトリを生成するため、1 つのアタッチメントのディレクトリは、2 つのターゲットのどちらがレンダリングしても同じ綴りになります。
ブロックの名前は、その source が指すディレクトリから導出されます。 その際、Terraform のモジュール名の文法に含まれない文字はアンダースコアに置き換えられます。この対応は一対一ではないため、2 つのコントリビューターが同じモジュール名になる場合、ビルドは Terraform が拒否する設定を出力するのではなく、停止して両方を示します。
アタッチメントが専用のモジュールであることから、次の 3 つのことが導かれます。
入力はそのアタッチメント自身のマッピングによるものです。 FeatureRecipe がモジュールをソース指定し valuesMapping を宣言するアタッチメントでは、そのマッピングが生成する値が、コンポーネントのソース指定モジュールが値を受け取るのと同じ形で、自身の module ブロックの引数として書かれます。valuesMapping を宣言しない FeatureRecipe はモジュールに引数を渡しません。モジュールが default 付きで宣言した変数はその値を取り、デフォルトなしで宣言された変数は未設定のままになるため、Terraform は plan を拒否します。
リソースは境界の単一の依存グラフに置かれます。 参照や depends_on はアタッチメントとアタッチ先のコンポーネントの間で届き、1 回の terraform plan で両方が見えます。これはルートが子を合成する構造がコンポーネントに与えるのと同じ性質であり、理由も同じです。
トップレベルの名前はそのアタッチメント自身のものです。 前述の名前空間の統合はディレクトリ単位で行われるため、専用のディレクトリに置かれたコントリビューターは、隣接するものと競合することなく output、variable、resource、locals の名前を宣言できます。そのため、アタッチメントはホストがすでに宣言している名前を再利用でき、互いに相手が何に何と名付けたかを知る必要はありません。
このターゲットが 要求しない ことに注意してください。チャートターゲットの制約は異なり、共通のレイアウトから実際以上のことが読み取られかねないためです。別のコントリビューターのディレクトリの内側にネストされたモジュールも、ここでは到達可能です。ルート設定は各コントリビューターの source を、識別子から再構築するのではなく、ビルドが合成した位置から読み取るからです。このターゲットが拒否するのは、2 つのコントリビューターがディレクトリを 共有 することです。チャートターゲットは、子チャートを 1 階層下でのみ探索しそれより深くは探さないため、ネストされた位置そのものを拒否します。
サポートされる入力の種類
terraform プロバイダは、3 つある Recipe の入力の種類のうち 2 つを受け付けます。
- Artifacts モード。 Recipe は Terraform 設定をテンプレート化された本文として記述します。プロバイダは Aggrega テンプレートを評価し、その結果を書き換えずに出力します。HCL(
main.tf)が扱いやすいデフォルトであり、Terraform JSON(.tf.json)も同等に受け付けられます。ビルドの来歴は、HCL の本文の先頭に Terraform コメントのブロックとして記録されます。コメント構文を持たない JSON の本文では、来歴はインラインではなく付随ファイルaggrega.provenance.tfとして書き出されます。 - Sourced モード。 Recipe は
source:で Terraform モジュールを参照します。モジュールのファイルはそのコンポーネントのディレクトリにそのままベンダリングされ、Recipe のvaluesMapping:は、境界のルート設定におけるそのコンポーネントのmoduleブロックの引数になります。モジュール本体は記述されたとおりに保持され、そこには何も書き込まれません。値はルートで一度だけ記述され、Terraform がそこで評価します。ノードで宣言されたvaluesのリーフがそのままモジュールの入力になる場合(valuesMapping:を持たないsource:Recipe)、作成者が機密として宣言した内容を持つ入力には、Terraform 自身の機密属性を持つ生成されたオーバーライドファイルも付与されます。valuesMapping:テンプレートは出力名を独自に作り出すため、その場合はマーキングが付かず、ビルドは勧告としてそれを報告します。どちらも 宣言された機密のモジュール入力 で説明しています。
valuesMapping: 内の null は null の引数です。 マッピングが null に設定したキーはモジュールブロックに <name> = null として書き込まれ、エンジンはモジュールの変数に default を上書きして値 null を与えます。ただし、変数が nullable = false を宣言している場合は default が適用されます。入力にモジュールのデフォルトを与えるには、そのキーをマッピングから省いてください。
synthesized 入力の種類は提供されません。プラットフォームの Workload の種類から任意の Terraform リソースへの、忠実で機能に依存しないマッピングは存在しないため、terraform プロバイダに対して workload: を宣言する Recipe は、独自の変換を作り出すのではなく明示的なエラーになります。
omits: を宣言する Recipe は拒否されます。 omits: キーはソースがレンダリングするドキュメントをビルドから除外するものですが、このプロバイダはビルド時に sourced モジュールから何もレンダリングしません。モジュールのファイルをそのままベンダリングし、設定が plan および apply されるときに Terraform がそれを評価します。レンダリングされるものがなければ除外するものもないため、このプロバイダはこのキーに従うことを宣言しておらず、これを宣言する Recipe や FeatureRecipe は何かがベンダリングされる前に拒否されます。The provider does not support omits(プロバイダは omits をサポートしていません) を参照してください。Recipe の横に置いたモジュールについては、そこにある .aggregaignore に行を追加すると、次に Recipe がピン留めされたときから、代わりにモジュールのファイルを除外できます。
レジストリが公開するモジュールをソースにする
モジュールレジストリは、モジュールの各バージョンをそのモジュール自身の git リポジトリのタグとして公開し、バージョンのダウンロードを求められたときに返すのは、そのタグが指すコミットにピン留めされた git ソースです。したがって Recipe は、git-repository ソース種別を使って、公開されたモジュールをそのリポジトリのそのタグからソースにします。
spec: capability: terraform implements: example/storage/database:1.0.0 source: kind: git-repository url: https://github.com/terraform-aws-modules/terraform-aws-rds.git ref: v7.2.2 valuesMapping: | identifier: "{{ .values.identifier }}" provides: host: "${module.{{ .context.instance_id }}.db_instance_address}" port: "${module.{{ .context.instance_id }}.db_instance_port}"ref: は、リポジトリが名付けたとおりのリリースタグです。valuesMapping: は、モジュールの variable ブロックが宣言する名前でモジュールの入力を与えます(Terraform は default を宣言していないすべての入力に値を要求します)。これらは、他の sourced モジュールと同様に、ルート設定におけるこのコンポーネントの module ブロックの引数になります。
何がピン留めされるか。 aggrega pin と pull は、タグをそれが指すコミットに解決し、そのコミットでリポジトリをアーカイブします。その後 Release のロックファイルには、そのコミットがソースのピン留めされたバージョンとして、タグが記述した参照として、そしてアーカイブのダイジェストが記録されます。以降のビルドはすべてキャッシュからアーカイブを読み込み、何かをベンダリングする前にそのダイジェストと照合するため、ネットワークを必要とせず、バイトが一致しなくなったキャッシュ済みアーカイブはビルドを停止させます。タグはリポジトリが別のコミットへ移動できる名前です。後の pull で、タグが別の場所に解決されることが判明した場合は、新しいコミットを採用せずに停止し、aggrega pull --upgrade によって意図的に採用します。これは Terraform 自身の依存関係ロックファイルよりも厳密なピン留めです。そのロックファイルは設定が選択したプロバイダを記録し、モジュールは一切記録しないため、タグ付きの git ソースとして設定に書かれたモジュールは、そのタグと同程度にしか固定されません。ここでは、モジュールのコミットとそのバイトのダイジェストがロックに固定され、バイトは出力にベンダリングされ、ルート設定はそれをローカルパスで呼び出すため、エンジンはモジュール自体を読み込むために何も取得しません。ただし、ベンダリングされたモジュールがレジストリやリモートのソースで呼び出すモジュールは引き続き取得され、ビルドはそのような呼び出しをそれぞれ報告します。詳しくは エンジンが初期化時に取得するモジュール呼び出し を参照してください。
何がベンダリングされるか。 ピン留めされたコミットのリポジトリ全体が、.git/ ディレクトリを除いて、modules/ 配下のコンポーネント自身のディレクトリにバイト単位でそのまま配置されます。モジュール自身の設定ファイルと子モジュールに加え、リポジトリに含まれるその他のもの、つまり examples/ や wrappers/ ディレクトリ、ドキュメント、CI 設定、バイナリを含むテストフィクスチャもすべて含まれます。エンジンが読み込むのはモジュールが呼び出すものだけです。ルート設定がコンポーネントのディレクトリを呼び出すと、エンジンはその直下の設定ファイルと、そこからローカルの source が到達する各ディレクトリの設定ファイルを読み込みます。そのため、他のレジストリモジュールを呼び出す example ディレクトリはベンダリングされても読み込まれることはなく、それが呼び出すものも取得されません。
ベンダリング対象を絞り込む。 取得されたソースは取得時のアーカイブそのものであるため、絞り込む唯一の方法は module_subdir: で、リポジトリの 1 つのディレクトリを成果物にします。これが役立つのは、目的のモジュールがサブディレクトリにある場合だけです。リポジトリのルートにあり自身の ./modules/* を呼び出すモジュールには、ツリー全体が必要です。リポジトリに含まれる .terraformignore も、Recipe の横にある .aggregaignore も、取得されたソースがベンダリングする内容を変えません。どちらも Recipe の横に置かれたモジュールを形作るものであり、リポジトリから取得されたモジュールについてはどちらも読まれません。
モジュールが公開するものを読む。 モジュールが公開する値はその output ブロックのいずれかであり、コンシューマはそれを ${module.<name>.<output>} として読みます。ここで <name> はプロデューサのモジュールブロックです。上のプロデューサが ${module.{{ .context.instance_id }}.<output>} を公開しているのはこのためです。エンジンはルート設定を検証するときに、モジュール自身の output ブロックに対して参照を解決するため、モジュールが宣言していない出力名はそこで、その名前を示して拒否されます。
Error: Unsupported attribute on aggrega.modules.tf line 9, in module "api": 9: db_host = "${module.db.db_instance_addresz}"This object does not have an attribute named "db_instance_addresz".ビルドはモジュールの variable ブロックも output ブロックも読まず、モジュールに何も書き込まず、プロバイダ設定も追加しないため、出力名の入力ミスはビルドではなくエンジンによって検出されます。コンシューマ側については 別のコンポーネントが公開する値を利用する を参照してください。
そのままの出力とベンダリング
terraform プロバイダは Terraform の本体をトランスパイル、再フォーマット、書き換えのいずれも行いません。作成された HCL または .tf.json の本体はテンプレートの評価結果どおりに出力され(HCL の本体は来歴コメントで始まります)、ソースから取得したモジュールはファイル単位でそのままベンダリングされます。これにより terraform の出力は決定的かつ再現可能になります。同じ入力であれば、レンダリングされた設定は実行ごとにバイト単位で同一となり、ベンダリングされたモジュールは変更されずにそのまま往復します。プロバイダは実行時の状態を解決しないため、実行時に依存するものはすべて、Terraform が apply 時にバインドする補間文字列のまま残ります。
プラットフォームアノテーション
terraform provider は aggrega.ai/ アノテーションをいずれも読み取りません。ベンダリングされたモジュール、Recipe のアーティファクトファイル、provider が書き出すルート構成には、名前空間、レジストリプレフィックス、プルシークレット、サービスアカウントを置く場所がないため、これらのいずれかに設定した値はレンダリングされる構成を何も変えません。そのような値を必要とするモジュールは、コンポーネントの values を通じて、それを自身の入力の一つとして受け取ります。
provider はこのことを Plugin エンティティで readsNoWellKnownAnnotations: true により宣言しており(Plugin エンティティを参照)、そのためビルドは、この provider を通じてレンダーに到達するすべての aggrega.ai/ アノテーションについて、そのレンダーが宣言する入力の種類を挙げ、キーごと・レンダーごとに 1 回ずつ警告します:
warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored it値は変更されずにそのままビルドを通過し、ビルドは停止しません。境界のアノテーションはその下のすべてのコンポーネントにカスケードし、コンポーネントが異なる対象を通じてレンダーされる境界は誤りではなく通常のものだからです。この警告は unsupported-field クラスに属し、そのクラスのフラグで抑制できます。
機密と宣言されたモジュール入力
Terraform は、値ごとのネイティブな機密性プリミティブを持つ唯一の標準ライブラリのターゲットです。そのため、作成者が機密と宣言したデータは、Aggrega 側で記録されるだけでなく、Terraform 自身の仕組みでレンダリングできます。
ベンダリングされたモジュールの入力が、作成者が機密と宣言した内容を含む場合、プロバイダはモジュールの横にもう 1 つファイル aggrega_override.tf.json を追加し、その入力に対して sensitive = true を宣言します。
{ "variable": { "db_password": { "sensitive": true } }}Terraform は、名前が単独の override であるか _override で終わる設定ファイルを、同じディレクトリ内の設定にマージします。そのため、モジュール自身の variable ブロックがこの属性を得る一方で、ベンダリングされたバイトはすべて作成されたとおりに保たれます。入力の宣言された型、デフォルト値、説明には手を加えません。オーバーライドが持つのは機密性の属性だけです。マークされていないノードには、このようなファイルは追加されません。
この制限はファイル形式が課すものではなく、意図的なものです。 オーバーライドには 2 つ目の属性を拒むものは何もなく、ベンダリングされたモジュールのバイトを編集せずに値を渡したい場合、variable ブロックの default が最も手近な場所です。しかし、その値は届きません。このファイルが記述されている JSON 設定構文における default は Terraform が評価する位置ではないため、そこに書かれた ${ ... } ポインタを含む値は、ポインタの文字列そのものとしてモジュールに届き、plan は成功して何も報告しません。同じポインタをネイティブ HCL の default に書くと即座に拒否されるため、この沈黙はオーバーライドファイルそのものではなく、この構文に起因します。したがって、オーバーライドは sensitive だけを持ちます。その意味は評価されるかどうかに依存しないからです。
どの入力をマークするかは宣言から決まり、名前からは決まりません。 プロバイダはコンパイルが算出したマーキングを読み取るだけで、自身では何も検査しません。password、secret、token を認識することはなく、推測のためにモジュールのテキストを読むこともありません。値に宣言のない db_password という名前のモジュール入力はマークされずに出力され、宣言された region という名前の入力はマークされます。
マーキングが伝わるのは、宣言から入力の同一性を復元できる場合だけです。 source: でモジュールをベンダリングし、ノードの宣言した values のリーフをそのままモジュールの入力とする Recipe では、各入力は作成者が宣言したのと同じ名前を持つため、対応関係は正確です。同じ方法でモジュールをベンダリングする component にアタッチされた Feature の FeatureRecipe も、その Feature が宣言するリーフについて同様です。valuesMapping: テンプレートでこれらの値を組み替える Recipe やそのような FeatureRecipe は、出力名を独自に作り出し、それを名指す宣言はありません。そのため、マーキングは近似されるのではなく付与されず、ビルドは宣言されたリーフごとに 1 件のアドバイザリでその旨を報告し、リーフとそのマッピングを持つエンティティを示します(boundary にアタッチされた Feature は values をまったく使わずにレンダリングされるため、マークするものがなく、アドバイザリも出ません)。A declared-sensitive value reaches the target through a values mapping(機密と宣言された値が values マッピングを通じてターゲットに到達しています) を参照してください。付与しないのは意図的です。組み替えられたどの入力が宣言されたデータを運んだかを推測すると、公開の入力を機密としてマークしてしまい、Terraform は機密でなかった値を plan 出力から隠すことになります。
作業例 terraform-declared-sensitivity はこれを端から端まで構築しており、全体を読み通せるほど小規模です。1 つの component が 3 つの values リーフを宣言し、そのうち 2 つは公開の識別子を、1 つは認証情報を持ちます。レンダリングされた出力では、module ブロックの引数が 3 つのモジュール入力すべてを持ち、オーバーライドは宣言された 1 つだけを指定しているため、規則の両面が同じビルドで確認できます。秘密情報の横にある認証情報の識別子がマークされないことも含めてです。その 1 つの宣言を削除して再ビルドすると、オーバーライドファイルはまったく出力されません。
Terraform の sensitive が保証すること、保証しないこと
Aggrega が約束するのは、Terraform 自身の属性が提供することそのものであり、それ以上ではありません。
表示を制限します。 機密の値は plan 出力では (sensitive value)、apply 出力では <sensitive> と表示されます。マーキングは式を通じて伝播するため、機密の入力から派生した値も機密となり、Terraform は、それ自体が機密とマークされていないルートの output からそのような値をエクスポートすることを拒否します。これは暗黙の漏洩ではなく、明示的なエラーになります。
ストレージは変わらず、暗号化でもありません。 Terraform は機密の値を state に平文で記録します。sensitive = true を、state をコミットや共有しても安全だという約束と読むことは、避けるべき唯一の誤解です。state の保護は、マーキングをまったく持たないモジュールの場合とまったく同じく、state バックエンドの設定方法の問題のままです。また、この属性は値を読める人を制限せず、provider が送信する内容にも影響せず、レンダリングされた設定をそれ以外の点で変えることもありません。
つまり、マーキングは、誰かが plan を読む際に、機密と宣言された入力が誤って漏洩しにくくなるようにします。デプロイ可能な成果物を公開しても安全にするものではありません。キーワードと、宣言がすべてのターゲットで何を実現するかについては、リーフを機密と宣言する を参照してください。
構造的な入力検証
terraform プロバイダーは、ソース指定されたモジュールの構造をレンダリングの前に検証します。モジュールの HCL ファイルと .tf.json ファイルを解析して解析エラーを報告し、問題のあるノードとプロバイダーを示す明確なメッセージとともにビルドを停止します。この解析が確認するのは形状であり、意味論ではありません。プロバイダーの解決、式の評価、レジストリへの接続は行いません。検証はハーメティックです。プロバイダーに組み込まれた自己完結型の HCL パーサーを使用し、terraform バイナリもネットワークアクセスも使いません。不正な形式のモジュールは、後の terraform 実行時に分かりにくいエラーとして表面化するのではなく、オーサリングの境界で検出されます。
エンジンが初期化時に取得するモジュール呼び出し
同じ読み取りでは、設定の初期化時に Terraform がソースをダウンロードする各 module ブロックを、何も拒否しない警告として報告します。ベンダリングされたモジュールのコミットとアーカイブダイジェストはロックで固定されますが、その内部にある module ブロックの source がレジストリアドレス、git・Mercurial・HTTP のアーカイブ URL、S3 または GCS のバケット、あるいは絶対パスである場合、そのブロックはエンジンが初期化時に、その時点で選択した任意のバージョンで取得するモジュールを指します。そして Terraform 自身の依存関係ロックファイルが記録するのはプロバイダーのみであるため、そのモジュールを固定するものは何もありません。ベンダリングされたモジュールの外へ出るローカルの source も報告されます。ビルドがベンダリングしていないファイルを指すためです。各検出結果は、ノードとプロバイダー、続いてブロック、その所在のファイルと行、および記述されたとおりのソースを示します。
warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that module読み取られるもの。 モジュールが呼び出されたときにエンジンが読み込むファイルです。まずモジュール自身のディレクトリ直下にある設定ファイル、次にそこからローカルの source(./ または ../ で始まるもの、あるいはそれらのバックスラッシュ表記)が到達する各ディレクトリ内のファイルを、ディレクトリからディレクトリへとたどり、それぞれ 1 回ずつ読み取ります。何からも呼び出されないディレクトリは読み取られないため、モジュールの examples/ や tests/ ディレクトリが行う呼び出しは報告されません。エンジンはモジュールが呼び出されたときにそれらを読み込むことはなく、それらが呼び出すものが取得されることもありません。上述の解析チェックは、引き続きすべてのベンダリングされた設定ファイルを解析します。Recipe のオーサリングされた本体も、レンダリング時に、本体が書き込まれるディレクトリから始めて同じ方法で読み取られるため、オーサリングされた本体がレジストリソースで記述する module ブロックも報告されます。spec.boundary.artifacts 配下のファイルはコンパイラ自身が評価して書き込み、どのプロバイダーにも渡されないため、そこに記述された module ブロックは読み取られず、警告も発生しません。
読み取られないもの。 読み取られるのは source が示す内容のみです。ビルドは呼び出しが指すモジュールを読み取らず、そのモジュールが何をするかを判断せず、呼び出しが許容されるかどうかも決定しません。エンジンが記述どおりに読むのではなく評価する source(補間や参照を含むもの)は、先頭のテキストで判断されます。アドレスで始まるものは記述どおりに報告され、ローカルの接頭辞や補間そのもので始まるものは、報告もされず、たどられもしません。行き先がテキストに含まれていないためです。required_providers 内の source はモジュールではなくプロバイダーを指し、モジュール呼び出しではありません。
拒否せずに報告する理由。 別のモジュールを呼び出すモジュールは正当な入力です。Terraform は呼び出されたモジュールを取得し、設定は機能します。作成者が手放すのは呼び出されたモジュールに対するビルドの固定であり、これは修正すべき欠陥ではなく知っておく価値のある事実です。その取得が許容されるかどうかは作成者の判断に委ねられます。完全に固定された状態を保つ必要がある設定では、そのような呼び出しを行わないモジュールのみをベンダリングします。この警告、そのクラスコード、およびほかにどこへ及ぶかについては、Warnings and Linter Output(警告とリンター出力)で説明しています。
FeatureRecipe のパッチ境界
レンダリング後に実行される FeatureRecipe の pipeline ステップがパッチを適用できるのは、プロバイダが構造化ツリーとしてレンダリングした出力だけです。terraform の場合、これは次のことを意味します。
- JSON で記述された Terraform はパッチ可能です。
.tf.jsonモジュールは構造化ドキュメントであるため、パイプラインステップの JSONPatch は指定された値をその場で編集し、それ以外のバイト(順序、書式、周囲のキー)にはまったく手を加えません。 - ネイティブ HCL は不透明です。 ネイティブ HCL の本体(
main.tf)は構造化されたパッチ対象ではありません。不透明な本体に対するパッチは、構造的に指定できないテキストを書き換えるのではなく、診断メッセージとともにビルドを停止させます。HCL 本体に対してパイプラインステップを記述することは設計上の誤りであり、何もせずに黙って終わるのではなく、明示的な停止として表面化します。 - ソースから取得したモジュールの入力は、そもそもパッチ対象ではありません。 これらはコンポーネントの
moduleブロックの引数であり、このブロックはルート設定内にあります。つまりネイティブ HCL であるため不透明であり、また特定の 1 つのノードではなく境界全体の成果物です。pipelineステップがパッチを適用するのはノード自身のレンダリング出力であるため、それらの入力を指定できる位置は存在しません。
したがって、Terraform の本体をパイプラインでパッチ可能にする必要がある場合は、.tf.json として記述します。プロバイダ全体にわたる一般的なパッチ対象の境界については FeatureRecipe を参照してください。
デプロイの順序付け
Release の境界の syncWave: の値は、その境界が組み込まれるルート構成の module ブロックを順序付けます。境界内のすべてのコンポーネントは境界のウェーブを継承します。複数の境界が同じ出力ディレクトリに解決され、それらのコンポーネントが単一のルート構成に合成される場合、そのルートは複数のウェーブを持ち、プロバイダはウェーブ間の順序を module ブロックの depends_on として表現します。
各モジュールは、component を持つ直前の wave のすべてのモジュールを指定し、それより前の wave は指定しません。 残りは Terraform が連鎖させます。wave 2 のモジュールは wave 1 に依存し、それは wave 0 に依存するため、各モジュール自身のリストはバウンダリ全体ではなく 1 つの wave の大きさに収まったまま、シーケンス全体が順序付けられます。wave は連続している必要はなく、負の値もごく普通に使われます。-1 は、構成の残りの部分が読み取るバケットやロールによく選ばれる値です。最も低い wave の前には何もないため、その wave は何も指定しません。
この順序が意味するもの:Terraform がアクションを実行する順序です。 Terraform は依存関係グラフを構築し、グラフが許す範囲で並列に処理します。depends_on はそのグラフにエッジを追加するため、Terraform は指定されたモジュールに対するアクションを完了してから、依存関係を宣言したモジュールに対するアクションを開始します。したがってウェーブは実行を段階に分けます。前のウェーブのコンポーネントに対するアクションが行われてから、後のウェーブのコンポーネントに対するアクションが開始されます。
これは準備完了の順序付けではありません。 Terraform の構成にはリソースがサービス可能であるという概念がないため、ここではリソースが準備完了になるのを待つことはなく、Terraform がそのリソースに対するアクションを終えるのを待つだけです。これは compose での同じウェーブとの実際の違いです。compose では healthcheck を宣言したサービスは healthy を報告するまで待機されます。compose にはゲートとなる準備完了のプリミティブがあり、Terraform の構成にはそれがありません。このターゲットが提供するのはアクションの順序であり、それを率直に述べるほうが、果たせない約束に注意書きを付けるよりも有用です。
削除の順序は約束されません。 depends_on が述べるのは、Terraform が依存先のアクションを完了してから依存元のアクションを開始するということです。destroy がそれらを削除する順序はその内容に含まれないため、ここでは削除の順序について何も主張しません。これは cloudformation で同じウェーブが持つ約束よりも狭いものです。cloudformation では属性が両方向を制御します。削除の順序付けをウェーブに頼っている場合は知っておく価値があります。このターゲットではウェーブは削除を順序付けないためです。
すべてのコンポーネントが同じ 1 つのウェーブを持つ境界は、これによって何も得ません。 syncWave をまったく宣言しない Release も同様です。すべての寄与要素はこのフィールドのデフォルト値 0 を持ち、ルート構成は単一のウェーブを持ち、出力されるバイト列は、プロバイダがウェーブの順序付けを表現しなかった場合とまったく同じになります。
2 つのルート構成にまたがる順序付けは表現できず、近似もされません。 Terraform の依存関係グラフは構成ごとに存在し、depends_on はそれを宣言した構成内のモジュールを指定するため、ウェーブはそのルートに合成されたすべてのコンポーネントを順序付け、それを越えるものは順序付けません。2 つの構成を順序付けるのはオペレーターの責任です。リモートステートの参照がビルド時ではなくデプロイ時に解決されるのと同じです。
ウェーブは実行に使われるだけでなく記録もされます。ノードの他のビルド来歴とともに、スタンプされたコメントブロック内の aggrega.ai/sync-wave として、または本体が JSON かベンダリングされたモジュールの場合は付随する来歴ファイル内に記録されます。そのため、レンダリングされた構成は、ウェーブによって順序付けられるだけでなく、その境界がどのウェーブを宣言したかも記録します。
ウェーブが表現しない順序付けは引き続き Terraform 自身の責任であり、その多くはリソース間の参照がすでに担っています。別のリソースの属性への参照は、そのリソースに先にアクションを行うよう Terraform に伝えます。参照もウェーブも示さない制約を必要とするモジュールは、モジュール内に独自の depends_on を記述します。プロバイダはそれを本体の他のすべての部分と同様にそのまま出力します。
関連リファレンス
- Provider アーキテクチャ — provider がコンパイルパイプラインとプロバイダーごとのディスパッチにどう組み込まれるか。
- Provider リファレンス索引 — 各標準ライブラリのプロバイダーが何を生成するか、またどのページがどの疑問に答えるか。
- Recipe エンティティ — Recipe のオーサリング面と 3 種類の入力。
- FeatureRecipe — レンダリング後の
pipelineパッチモデルと、その構造化/不透明の境界。 - Recipe 入力の合成 — 正規の Provider Capability Matrix。