コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

CloudFormation Provider

cloudformation プロバイダーは、Aggrega Recipes を AWS CloudFormation のスタックテンプレートにレンダリングします。このプロバイダーのもとで同じ出力ディレクトリにレンダリングされるすべてのコンポーネントは 1 つのスタックにまとめられ、ロングフォームの組み込み関数を使用する単一の純粋な JSON テンプレートとして出力されます。したがって、通常の場合、1 つの境界は 1 つのスタックになります。また、directory: が同じパスに解決される 2 つの境界は、まとめて 1 つのスタックに組み立てられ、そのテンプレートの名前を共有します。すべての Aggrega プロバイダーと同様に、このプロバイダーはオフラインかつ密閉的です。Aggrega のビルドは事前(ahead-of-time)コンパイルであるため、プロバイダーが AWS を呼び出すことはなく、アカウントで生成される識別子を解決することもなく、CloudFormation を実行することもありません。実行時にのみ決まる値は CloudFormation の組み込み参照(Fn::GetAtt、Fn::ImportValue、Fn::GetStackOutput)のまま残され、CloudFormation がデプロイ時に解決します。

スタックに組み立てられるフラグメント Recipe

cloudformation の Recipe は、テンプレート全体ではなくフラグメント、つまり単一のコンポーネントが提供する CloudFormation リソースを記述します。boundary のコンポーネントがレンダリングされると、Provider はディスパッチグループ内のすべてのフラグメントを 1 つのスタックテンプレートに組み立てます。リソースは単一の Resources マップの下にマージされ、各コンポーネントの provides の値はスタックの Outputs として公開され、テンプレートのその他のトップレベルセクションは 組み立てられたスタックのトップレベルセクション で 1 つずつ扱われます。受け付ける記述形式は 2 つです。

  • フラグメント(artifacts)入力。 Recipe がリソースフラグメントを直接記述します。Provider はそれを純粋な JSON の長形式組み込み関数に正規化し、組み立てられたスタックにマージします。
  • ソース入力。 Recipe が既存の CloudFormation テンプレート(YAML または JSON)を参照します。Provider はそれを長形式の JSON に正規化して組み立て前にその構造を検証し、テンプレートが宣言するパラメータを Recipe の valuesMapping から埋め(ソーステンプレートのパラメータの値 を参照)、Recipe の omits: エントリが指定するリソースを除外します(ソーステンプレートからリソースを除外する を参照)。

組み立てられたテンプレートは純粋な JSON です。組み込み関数はそのまま出力され、ビルド時に評価されることはありません。コンパイラはスタックのデプロイ後にしか存在しない値を解決できず、それを評価すれば事前コンパイルの契約が崩れるためです。

コンポーネントにアタッチされた Feature は同じスタックに寄与する

コンポーネントにアタッチされた Feature は、ホストコンポーネント自身の Recipe と同じ条件で、ホストコンポーネントが組み立てられるスタックに自身のリソースを提供します。その横に別のテンプレートはありません。組み立てられたスタックが、この Provider が出力ディレクトリに対して出力するもののすべてであるため、アタッチされた Feature のリソースはそのスタックに含まれるか、まったくデプロイされないかのどちらかです。Feature をデタッチすると、ちょうどそれらのリソースが削除され、ホストコンポーネント自身のリソースはそのまま残ります。

それらは組み立てられたスタックに配置されるため、その名前空間を共有します。アタッチされた Feature のリソース論理 ID は、ホストコンポーネントのもの、および並んでアタッチされた他のすべての Feature のものと同じ空間に置かれるため、組み立てられたスタックでの名前 がそのまま適用されます。2 つの提供元が 1 つの名前で衝突した場合、停止メッセージはコンポーネントと、Feature がアタッチされているキーを示すため、衝突の両端を自分のファイル内で検索できます。

アタッチされた Feature の出力はホストコンポーネントの名前で公開されますが、そのリソース論理 ID はそうではありません。 スタックの 2 つの部分は異なる規則で命名されるため、この点についての扱いも異なります。リソース論理 ID は、他の Recipe と同様に FeatureRecipe が記述したとおりに出力されます。出力は公開元コンポーネントとエントリの組み合わせで命名され、コンポーネントにアタッチされた Feature の場合、公開元コンポーネントはホストです。payments-db にアタッチされ alarm を公開する Feature は paymentsXzhdbXXalarm になり、これはホストコンポーネント自身がそのエントリを公開した場合と同じ名前です。そのため、ホストも公開するエントリ名はアタッチメントのものと 1 つの出力名で衝突し、ビルドはコンポーネントと Feature がアタッチされているキーを、コンポーネント単独のものと並べて示して停止します。alarm ではなく backup-alarm のように Feature 固有と読めるエントリ名を選ぶと、ホストのものとの衝突を避けられます。

Feature が提供する各リソースは、ビルドがそこに書き込む来歴の中に、ホストコンポーネントのものではなく、そのアタッチメント用に構成された識別情報を保持します。そのため、両者が提供したスタック内でも 2 つを区別できます。その識別情報の構成方法は ラベルとアノテーション で説明しています。

組み立てられたスタックのトップレベルセクション

複数のコンポーネントが 1 つのスタックに組み立てられるため、CloudFormation テンプレートが認めるすべてのトップレベルセクションを、組み立ての際に扱う必要があります。これには、CloudFormation がホストするトランスフォームがテンプレート言語に追加する 2 つのセクション、Globals と Hooks も含まれます。各セクションは以下のグループのちょうど 1 つに分類され、コンポーネントが書いたトップレベルキーがどのセクションにも該当しない場合は、そのコンポーネントとキーを示す警告が出ます。そのため、何も告げられずに破棄されるものはありません。

プロバイダがスコープを付けた名前で組み立てられるもの、または書かれたとおりに読まれるもの。 Resources と Outputs です。これらについては 組み立てられたスタックの名前で詳しく説明します。AWSTemplateFormatVersion はどのコンポーネントからも読み取られず、プロバイダが書き込みます。テンプレート言語はこれに単一の値しか認めないため、コンポーネントが決めることは何もありません。

書いた名前のまま運ばれるもの。 Parameters、Mappings、Conditions、Metadata、Rules です。これらはいずれも自分で選んだ名前をキーとするマップであるため、各コンポーネントのエントリはその名前のまま、書き換えられずに組み立てられたスタックに届きます。これにより、リソースの Condition:、Fn::FindInMap、パラメータへの Ref が、一緒に届いた宣言に対して解決されます。それぞれは個別に記述されるため、個別に運ばれます。ルールは同じドキュメントのパラメータに対してアサーションを行い、条件はパラメータをまったく参照しないこともあり、CloudFormation はマッピング内でのパラメータ参照を許可しません。

ここでは 1 つの語が 2 つの異なる場所を指しており、自分のものはそのうち最初の 1 つだけです。上のリストにある Metadata はテンプレート自体のトップレベルセクションで、自分で選んだ名前のマップです。個々のリソースもそれ自身の Metadata 属性を持ち、ビルドはそこに来歴を書き込みます。書き込み先は予約された単一の aggrega.ai/ キーの下で、そこに書いた内容を置き換えずに、その横に追加されます。したがって、リソース内に現れる来歴エントリは、自分で記述したものでも、トップレベルセクションが運んだものでもありません。

Parameters、Mappings、Conditions、Rules は、エントリに論理 ID で名前を付けます。 プロバイダは名前を書かれたとおりに運ぶため、論理 ID が認める文字集合はこれらのセクションにも及びます。この 4 つのいずれかで、英字と数字以外を含む名前はビルドを停止させます。運ばれるセクション名が文字集合の外にあると停止するを参照してください。プロバイダはトップレベルの Metadata セクションの名前にはこの文字集合を求めません。それらの名前は、テンプレートが参照する何かではなく、保存する情報を名付けるものだからです。

2 つのコンポーネントがこれらのセクションのいずれかで異なる名前を宣言した場合、両方が反映されます。同じ名前を同一の内容で宣言した場合は 1 つのエントリにマージされ、ビルドは続行します。同じ名前を異なる内容で宣言した場合はビルドが停止し、セクション、名前、両方のコンポーネントが示されます。そうしなければ 2 つの本体のうち一方が破棄され、それを書いたコンポーネントに、スタックが運ばない宣言が残ることになるためです。これはリソース名と出力名が従う調整と同じであり、どちらか一方の名前を変更すれば解消します。

運ばれずに名指しされるもの。 Description は、自分で選んだ名前のマップではなく、テンプレート全体についての単一の記述であるため、複数のコンポーネントから組み立てる場合には答えがありません。2 つの説明は 1 つの問いへの 2 つの答えであり、どちらもスタックのものではありません。Hooks は AWS::CodeDeployBlueGreen トランスフォームだけが読み取りますが、組み立てられたスタックがこれを運ぶことはありません(下記参照)。したがって、組み立てられたスタックはどちらも運ばず、それらを記述したすべてのコンポーネントに、コンポーネントとセクションを示す警告が出ます。Globals を書きながら、それを読み取る AWS::Serverless-2016-10-31 トランスフォームを宣言していないコンポーネントも同様です。この警告は助言的で帯域外のものです。出力されるテンプレートは警告がない場合とバイト単位で同一であり、--no-unsupported-field-warnings で同じ種類の他の警告とともに抑止できます。

Transform はすべてのコンポーネントのものから組み立てられます。 トランスフォームは、CloudFormation が何かをデプロイする前にテンプレート全体に対して実行するマクロです。そのため、組み立てられたスタックの Transform は、コンポーネントが宣言するトランスフォーム(ソースされたテンプレートのものもフラグメントのものも同様)の和集合となり、CloudFormation が文書化している順序に並びます。アカウントで定義したマクロは CloudFormation がホストするトランスフォームより前に、AWS::LanguageExtensions は AWS::Serverless-2016-10-31 より前に置かれます。各コンポーネント自身の順序は保たれ、順序の定まらない 2 つのトランスフォームはコンポーネントが最初に宣言した順に実行されるため、同じコンポーネントからは同じスタックが得られます。トランスフォームが 1 つなら文字列として、複数ならリストとして書かれます。コンポーネントが 1 つだけで、その Transform を 1 つのテンプレートまたはフラグメントで宣言しているスタックでは、下の表がそれを運ぶ限り、書かれたとおりに保持されます。どのコンポーネントも宣言しないスタックは何も運びません。コンポーネントのトランスフォームは警告を出しません。運ばれるか、それを示してビルドが停止するかのどちらかです。

トランスフォームはテンプレート全体を処理するため、それを運ぶと、その処理がそのトランスフォーム向けに書かれた内容に限定されない限り、他のすべてのコンポーネントの内容のデプロイのされ方が変わります。そこで各トランスフォームは、CloudFormation 自身のドキュメントが裏付ける扱いを受け、スタックが運べない組み合わせはビルドを停止させ、トランスフォームとスタック内のすべてのコンポーネントを示します。

トランスフォーム組み立てられたスタックでの扱い
AWS::Serverless-2016-10-31それを宣言するコンポーネントの Globals とともに運ばれます。その Globals が他のコンポーネントのサーバーレスリソースに及ぶ場合、およびそのリソースのイベントソースが他のコンポーネントの宣言するリソースを名指しする場合は停止します。トランスフォームはイベントが名指しするリソースを書き換えるためです。
AWS::LanguageExtensions単独で、または同じコンポーネントの AWS::Serverless-2016-10-31 と並んで運ばれます。他のコンポーネントのサーバーレスの内容と並ぶ場合は停止します。言語拡張が値を解決した後では、サーバーレストランスフォームが生成物に付ける名前が変わるためです。
AWS::SecretsManager-2020-07-23, AWS::SecretsManager-2024-09-16運ばれます。これらはそれを要求するローテーションスケジュールだけを処理します。
AWS::ServiceCatalogコンポーネントが 1 つだけのスタックでは運ばれます。他のものと並ぶと停止します。テンプレート内のあらゆる場所で参照パターンを置換するためです。
AWS::CodeDeployBlueGreen単独でも停止します。CloudFormation はこれを宣言するテンプレート内のどこでも Outputs と Fn::ImportValue を拒否しますが、組み立てられたスタックはコンポーネントが公開する出力を運ぶためです。
AWS::Include単独でも停止します。スタックのデプロイ時に S3 から取得した内容を挿入するため、ビルドはそれを読み取れません。
アカウントで定義したマクロコンポーネントが 1 つだけのスタックでは運ばれます。他のものと並ぶと停止します。テンプレートの残りの部分に何をするかがビルドにはわからないためです。

2 つのコンポーネントが同じ 2 つのトランスフォームを逆の順序で宣言した場合も、両方の順序と両方のコンポーネントを示してビルドが停止します。スタックはそれらを 1 つの順序でしか実行しないためです。スタックが運べないトランスフォームを必要とするコンポーネントは、専用のバウンダリに置きます。

組み立てられたスタック内の名前

CloudFormation の論理 ID は 1 つのテンプレート内で一意であり、英字と数字のみを受け付けます。そして、そのテンプレートに組み立てられるすべてのコンポーネントがその名前空間を共有します。両方が同じ出力ディレクトリに解決される場合は、別の境界のコンポーネントも含まれます。そのため、スタックが何かを指すのに使う各名前は、それを提供したすべてのコンポーネントの間で区別できなければならず、提供元の集合は必ずしも単一の境界とは限りません。

リソースの論理 ID は Recipe から得られます。 プロバイダーは論理 ID を記述されたとおりに出力し、どれも書き換えません。そのため、組み立てられたテンプレートで読める名前は Recipe が書いた名前です。標準ライブラリの CloudFormation Recipes は、コンポーネントインスタンス自身の名前から論理 ID を導出し、その名前の区切り文字を単語の境界として読みます。インスタンス payments-db はリソースを PaymentsDb と名付けます。したがって、同じ型の 2 つのインスタンスは 1 つのリソースを奪い合うのではなく、2 つのリソースを記述します。

出力名は、それを公開したコンポーネントによってスコープされます。 各 provides エントリは、公開元のコンポーネントとエントリを組み合わせて名付けられた出力として現れます。host を公開するコンポーネント payments-db は paymentsXzhdbXXhost として現れます。そのため、同じエントリを公開する 2 つのコンポーネントは別々の 2 つの出力になり、別のコンポーネントがスタックに加わっても出力の意味は変わりません。同じアカウントとリージョン内のスタック間のコンシューマーはこの名前ではなくエクスポート名でインポートするため、エクスポート名は影響を受けません。アカウント間またはリージョン間の読み取りは、プロバイダーが代わりに書き込むこの出力名を指定します(スタック間の配線を参照)。

出力名の構築方法

論理 ID は区切り文字を一切受け付けないため、記述したものから構築される名前は、何らかの方法で区切り文字を引き継がなければなりません。区切り文字を落とすと情報が失われます。payments-db と payments_db は 2 つのコンポーネントであり、句読点を落とした名前はどちらも識別できません。そこでプロバイダーは、受け付けられない文字を落とす代わりにエンコードし、受け付けられない各文字を、使用可能な文字で書き表します。

この方式はエスケープの開始に 1 文字、大文字の X を予約し、それ以外はすべて大文字も含めて入力したとおりに書きます。予約されるのは大文字のみであるため、nginx-proxy のような名前の小文字の x は記述したとおりに引き継がれます。

記述したもの変換後理由
英字または数字(X を除く)そのまま使用可能な文字である
-Xzhハイフンは使用できない
_Xzuアンダースコアは使用できない
.Xzdピリオドは使用できない
/Xzsスラッシュは使用できない(ネストされたコンポーネントの識別子に含まれる)
XXzx000058エスケープの開始に予約されているため、コードポイントで書き表される
その他Xzx とその文字のコードポイント残りのすべての文字を 1 つの規則で扱う
2 つの部分の結合XX開始文字が 2 つ連続したもので、どちらの部分にも含まれ得ない

逆方向に読み戻しても曖昧さは生じません。これは単なる利点ではなく、この方式の要点です。X がそれ自体として残されるのは、直後の文字がアルファベットで許される文字である場合に限られます。そのため、エンコードされた片側が X で終わることはなく、X が 2 つ連続することもありません。これにより、XX は結合の意味に使え、結合だけを意味します。

そのため、句読点の位置だけが異なる 3 つの名前も区別されます。

component payments-db publishing host → paymentsXzhdbXXhost
component payments_db publishing host → paymentsXzudbXXhost
component payments publishing db-host → paymentsXXdbXzhhost

名前は記述したコンポーネント名より長く、一目では読みにくくなりますが、それがトレードオフです。 1 つのエントリだけを正確に識別する名前は、2 つのどちらも識別できない短い名前より価値があります。また、出力はこの名前を入力するのではなくエクスポート名を通じて参照するため、代償は出力されたテンプレートを読むときにもう一度見直す手間だけです。

リソースの論理 ID には別の規則が適用されます。 プロバイダーは論理 ID を構築せず、Recipe が書いたものを出力するからです。標準ライブラリの CloudFormation Recipes は、インスタンス名の区切り文字を単語の境界として読んで論理 ID を導出します。インスタンス payments-db はリソースを PaymentsDb と名付けます。そしてこの導出は区切り文字を落とすため、句読点だけ、あるいは英字の大文字小文字だけが異なる 2 つのインスタンス名は、同じリソース名を導出します。ビルドは、2 つのコンポーネントが宣言されているのに 1 つのリソースを出力するのではなく停止し、その名前に至ったすべてのインスタンスと、行き着いた名前を示します。一部ではなくすべてを示すのは、衝突においてどれか 1 つのインスタンスの導出が意図されたものだと判断できる根拠がないためです。1 つを除いてすべての名前を変更すると解消します。

使用可能な文字以外を含むリソース論理 ID は停止します

一意性と使用可能な文字は別々の要件であり、名前の集合が前者を満たしても後者を満たさないことがあります。プロバイダーはリソースの論理 ID を Recipe が書いたとおりに出力するため、Recipe が書く ID は、それ自体で CloudFormation テンプレートが保持できるもの、つまり英字と数字のみでなければなりません。

ここで、構築される名前とそのまま渡される名前の扱いが分かれます。出力名はプロバイダーが公開元のコンポーネントとエントリをエンコードして構築するため、どちらの部分をどう綴っても、出力名は使用可能な文字の範囲内に収まります。リソースの論理 ID はそのまま渡されるため、Recipe が書いたものがそのままテンプレートに入ります。

そのため、Recipe がコンポーネントインスタンスの名前を論理 ID にそのまま書き込む場合には、これはコンポーネント名に対する制約にもなります。コンポーネント名にはハイフンやアンダースコアを含められますが、論理 ID には含められません。したがって、そのような Recipe を通じてこのプロバイダーを対象とするコンポーネントは、英字と数字のみで名付けます。payments-db ではなく paymentsdb とします。それ以外はビルドを停止させます。

停止時には、ID を書いた Recipe の提供元、ID そのもの、ID に含められない各文字が示され、代わりに何を書けるかも示されます。解消方法は 2 つあり、1 つ目は常に利用できます。

  • 名前をそのまま渡すのではなく、Recipe 自身に論理 ID を書かせます。標準ライブラリの CloudFormation Recipes はこの方法を取ります。インスタンス名の区切り文字を単語の境界として読むため、インスタンス payments-db はリソースを PaymentsDb と名付け、選んだコンポーネント名はそのまま保てます。この方法で ID を導出すると、この停止の代わりに上記の衝突の規則が適用されます。句読点だけが異なる 2 つのインスタンス名は、同じリソース名を導出します。
  • Recipe が名前をそのまま渡す場合は、渡されるものを英字と数字のみの名前に変更します。コンポーネント自身の Recipe では、それはコンポーネント名です。コンポーネントにアタッチされた Feature は、自身の FeatureRecipe からリソースを名付けるため、ホストコンポーネントの名前を変更してもそれらには及びません。変更が必要なのは、その Recipe が書く ID です。

プロバイダーは拒否し、黙って修正することはしません。 代わりに ID を書き換えるのは親切に見えますが、そうではありません。論理 ID は CloudFormation が更新をまたいでリソースを識別する手段であるため、論理 ID を変えることは名前の変更ではなく、別のリソースを指すことになります。プロバイダーが置き換えた ID は、記述した ID ですでにデプロイされているリソースとは別の場所を指し、しかもその置き換えは依頼していないもので、出力されたテンプレートから見つけ出さなければなりません。停止するビルドは、まだ自分で修正できる段階で問題を示します。

アルファベット外のセクション名はビルドを停止させる

provider が記述どおりに引き継ぐ名前は、リソースの論理 ID だけではありません。Parameters、Mappings、Conditions、Rules もそのエントリを論理 ID で名付け、この 4 つはいずれも作成者が選んだ名前のまま組み立て後のスタックに届きます。したがって、さらに 4 つの対象に同じ要件が課されます。名前は CloudFormation テンプレートがそれ自体で保持できるもの、つまり英字と数字のみでなければならず、それ以外はビルドを停止させます。

名前を持つセクションを越えた影響が 1 つあり、それが警告ではなく停止とする理由です。これらの名前は、リソースの Condition:、Fn::FindInMap、あるいはパラメータへの Ref の解決先です。そのため、アルファベットが許さない名前は、宣言そのものとともに、それを指す参照もデプロイ可能なテンプレートから外してしまいます。1 つの名前が両方を同時に届かなくするのです。停止がなければ、これはデプロイ時に、名前を書いた人ではなくデプロイする人によって発見されることになります。

停止メッセージは、その名前を書いた Recipe の提供元、名前が書かれたセクション、名前そのもの、そしてその中で使用できない各文字を示します。Recipes 内で検索すべき語はセクションです。これらの名前は書かれたセクションのまま引き継がれるため、メッセージと自分のファイルの両方に現れる唯一の語がセクションです。エントリ名を英字と数字のみに変更すれば解消し、対処法はそれだけです。リソースの論理 ID であれば、名前をそのまま渡す代わりに Recipe に ID を導出させるという代替手段がありますが、ここでは導出するものがありません。セクション内の名前こそが、書いた そのもの だからです。

アルファベットの制約を受けるのはセクション自体の名前だけで、エントリ内のキーは対象外です。 マッピングの 2 階層目のキーは自由に選べます。RegionCidr マップの下の us-east-1 はごく普通の例で、出力されるテンプレートにそのまま届きます。パラメータ、条件、ルールの本体内のキーは、スタックが参照するものではなく、属性、アサーション、組み込み関数を名付けるものです。ルールの Assertions や、その中に書かれた Fn::Contains がその種のキーです。いずれも論理 ID ではなく、検査されません。

区別して書いた 2 つのエントリ名は区別されたまま残る

1 つの出力名で衝突しうるほど近いエントリ名は 3 種類あり、どれも珍しいものではありません。2 つの部分は畳み込まれるのではなくエンコードされ、どちらの部分にも含まれ得ない並びで結合されるため、3 種類ともそれぞれ固有の名前になります。

  • 句読点だけが異なるエントリ。db-host と db_host の両方を公開する component は、dbXzhhost と dbXzuhost になります。
  • 文字の大小だけが異なるエントリ。host と Host は host と Host になります。文字は書いたとおりの大小で引き継がれるためです。
  • 結合部をまたいで一致するエントリ。host を公開する Component payments-db は paymentsXzhdbXXhost になり、db-host を公開する Component payments は paymentsXXdbXzhhost になります。

本当に 1 つのものを名付けている場合は、2 つのエントリはやはり一致します。 出力名は公開する component とエントリから作られるため、その両方を共有するものは、どうエンコードされても 1 つの名前になります。最も遭遇しやすいのは、1 つの Feature を 1 つの component に 2 回アタッチする場合です。アタッチメントはその ホスト の下で公開するため、1 つの component 上の 1 つの Feature の 2 つのアタッチメントは、どちらも payments-db から alarm-id を公開し、2 つを区別するものは何もありません。2 つ書かれた場所に 1 つの出力を出力するのではなく、ビルドは停止します。その際、component と各側が持っていたアタッチメントキーを示すので、両方を自分のファイルで検索できます。Feature を 1 回だけアタッチするか、公開エントリ名がそのアタッチメント固有のものとして読める Feature を使用してください。

これは 2 つのエントリが同じ値を持つかどうかにかかわらず成り立ちます。同じ値を持つ 2 つのエントリも、作成者が求めた 2 つの出力を表しているため、1 つに統合すると、書かれた 2 つの出力の一方がスタックから欠けてしまいます。

Recipe がテンプレート内で組み立てる名前はこの対象外

上記のエンコードは provider のものであり、provider が作る出力名に適用されます。Recipe テンプレート内では利用できないため、テンプレートが組み立てる名前にはその保証が一切ありません。 これを明言することが重要なのは、その危険がテンプレートの内側からは見えないからです。テンプレートで利用できる畳み込みは引数を単語として読み、単語間のものをすべて落とすため、2 つの値を畳み込む 前に 結合すると、句読点とともに結合部も失われます。

インスタンスとアタッチメントキーからリソースを名付け、スペースで結合してから畳み込む FeatureRecipe は、注意すべき形です。app と cache、および app-cache と空の組み合わせは、どちらも AppCache に畳み込まれ、畳み込みのどの性質が効く前に 2 つは衝突します。このような名前を区別しておく方法は 2 つあり、どちらも provider ではなく作成者の責任です。

  • 組み立てる部分を英字と数字に保つことで、何も落とされず、何も区別する必要がなくなります。
  • 互いの区切り文字をそれぞれ含みうる 2 つの値を結合しないでください。 名前が 2 つの部分を持つ必要がある場合は、一方を、もう一方が含み得ない固定リテラルにしてください。

組み立てた名前が衝突する場合、それは出力名ではなくリソースの論理 ID として衝突するため、遭遇する停止は上記のリソース名のものです。

1 つのマッピング内で 2 回書かれたキーはビルドを停止させる

CloudFormation フラグメントはマッピングとして読まれ、マッピングはキーごとに 1 つの値を保持するため、2 回書かれたキーは最後に来た本体を残し、もう一方を捨ててしまいます。マッピングが Resources または Outputs ブロックの場合、捨てられる本体は、書かれたにもかかわらずスタックにただ存在しないことになるリソースや出力です。

代わりにビルドは停止し、繰り返されたキーと、それが書かれた両方の行を示します。これはスタックの名前に関する規則ではなく、フラグメント全体に関する規則です。リソースの Properties を含め、フラグメント内のあらゆるマッピングに適用されます。最もよくある発生経路は、Recipe が記述された値から論理 ID を導出し、2 つの記述値が句読点だけ異なる場合です。app-cache と app_cache はどちらも AppCache を導出するため、フラグメントには AppCache が 2 回書かれます。

ドキュメント内の異なる場所で同じキー名が繰り返されるのは普通のことであり、影響を受けません。フラグメントが持つリソースと出力の数にかかわらず、Type はリソースごとに 1 回、Value は出力ごとに 1 回現れます。本体が失われるのは、1 つのマッピング内での繰り返しだけです。

1 つの component が 1 つの名前を 2 回主張することもあります。 Recipe は複数のフラグメントを提供します。複数の artifacts: エントリや、複数のテンプレートを持つソースディレクトリなどです。そのすべてが同じスタックに組み立てられるため、component 自身のフラグメント同士も、component 間と同様にスタックの名前を共有します。1 つの名前に異なる 2 つの本体を与える 2 つのフラグメントはビルドを停止させ、停止メッセージは、その名前が属するキー空間(リソースの論理 ID または出力名)を、component と名前そのものとともに示します。どちらの空間もこの経路で到達しえます。2 つのフラグメントが異なるリソースに対して 1 つのリソース論理 ID を記述することがあり、また component は明示的な Outputs: ブロックと provides: エントリという 2 つの経路で出力名に到達するため、それぞれから同じ名前を持つエントリが来れば、そこでも衝突します。

名前を再記述すること自体は競合ではありません。同一の内容で複数回書かれた名前はいずれにせよ 1 つのものを指すため、再記述は 1 つのエントリに統合され、ビルドは続行します。通常の繰り返しにコストはかかりません。停止するのは内容が失われる場合、つまり 2 つの本体の一方を捨てなければならず、Recipe が宣言したリソースや出力がスタックから欠けてしまう場合です。どちらか一方の名前を変更すれば解消します。

構造的な入力検証

ソースとして指定された CloudFormation テンプレートは、レンダリングの前に構造的に検証されます。provider はテンプレートをパースしてその組み込み関数を正規化し、テンプレートの形式が不正な場合は、問題のあるノードを示す明確なメッセージとともにビルドを停止します。このパースが確認するのは形状であり、意味ではありません。AWS への接続、参照の解決、組み込み関数の評価は行いません。

パースに成功したテンプレートが、それによって丸ごと引き継がれるわけではありません。 パースが示すのはドキュメントが整形式であることです。組み立てられたスタックに何が届くかは、組み立てられたスタックのトップレベルセクションのもとで、セクションごとに別途決まります。ソースとして指定されたテンプレートは、フラグメントと同じ扱いを受けます。

また、パースはテンプレートの参照が解決されるかどうかも問いません。Ref がパラメータを指しているか、Fn::FindInMap がマップを指しているかは、個々の入力ドキュメントではなく組み立てられたスタックについての問いであり、デプロイ時に CloudFormation が答えるものです。ビルドは、結果が何を参照しているかを判断する代わりに、引き継がなかったものを示します。ビルドが判断する参照は、ビルド自身が宙に浮かせたものです。ソースとして指定されたテンプレートのバインディングが値を埋めたパラメータへの参照(次のセクションで扱います)と、omits: のエントリがテンプレートから除外したリソースへの参照(その次のセクションで扱います)です。

ソースとなるテンプレートのパラメータに渡す値

ソースとなるテンプレートは、CloudFormation 自体がテンプレートに値を渡すのと同じ方法、つまりテンプレートが宣言する Parameters を通じて値を受け取ります。テンプレートをソースとして指定するもの(component の Recipe、またはアタッチされた Feature の FeatureRecipe)の valuesMapping は、埋めるパラメータごとに 1 つのキーを書き、プロバイダはソース内のすべてのテンプレートでそれぞれをバインドします。Resources、Outputs、Conditions、Rules、および SAM の Globals 内にあるそのパラメータへのすべての Ref は値に置き換わり、そのパラメータを変数として指定するすべての Fn::Sub は変数マップを通じて値を受け取り、そのパラメータはそれを宣言するすべてのテンプレートの Parameters から取り除かれます。どのキーも指定しないパラメータは、スタックのデプロイ時に渡される値またはその Default のために、テンプレートに書かれたとおりに残されます。

パラメータを宣言する単位はソースです。 ディレクトリソースのテンプレートは 1 つのスタックに組み立てられるため、あるテンプレートが、同じソースの別のテンプレートが宣言するパラメータを参照することがあります。パラメータを埋めると、そこでも埋められます。パラメータを参照するだけのテンプレートは、それを宣言するソース内の最初のテンプレートが変換したとおりの値を受け取り、バインドによって宣言が取り除かれたパラメータを参照したまま残るものはソース内にありません。

スタック内の他のものは、埋められたパラメータを参照できません。 ソースの外にあるコンテンツ(同じスタック内の別の component のフラグメントやソースとなるテンプレート)が、ソースのバインドによって埋められたパラメータを Ref、Fn::Sub の変数、またはルールの Fn::ValueOf を通じて指定すると、組み立てられたスタックがもはや宣言していないものを指定することになり、スタックのデプロイ時に CloudFormation がそれを拒否します。そのためビルドは停止し、各 component、そのテンプレートとパラメータ、そしてそのパラメータを埋めた valuesMapping(Recipe のもの、またはアタッチされた Feature の FeatureRecipe のもの)を持つ component を示します。component にアタッチされた Feature はその component によって示され、境界にアタッチされた Feature は、そのリソースが aggrega.ai/component-id として持つ識別子によって示されます。この識別子は境界のパスとアタッチメントの名前から構成されます(境界 stack 上のアタッチメント aux なら bfr--stack--aux)。Feature がアタッチされた component のフラグメント、または Feature がアタッチされた境界内の component のフラグメントが、アタッチメントのバインドによって埋められたパラメータを参照する場合も、ビルドは停止します。スタックがまだ宣言している名前は影響を受けません。別の component がその名前のパラメータを自ら宣言している場合や、リソースがそれを論理 ID として持つ場合、その参照はその宣言に解決され、書かれたとおりに残されます。値を引き渡すには、埋める側の component にそれを公開させるか、参照するテンプレートでパラメータを宣言するか、valuesMapping からキーを削除してください。

spec:
capability: cloudformation
implements: core/delivery-stream:1.0.0
source:
kind: git-repository
url: https://github.com/aws-cloudformation/aws-cloudformation-templates.git
ref: a0f43bc6d20813052892546f445037cf84c75b54
module_subdir: DataFirehose
valuesMapping: |
CloudWatchLogGroupRetention: {{ .values.retention_days }}
DestinationBucketName: "{{ .context.inject.env.BUCKET_NAME }}"

パラメータを埋めるのは valuesMapping だけです。 そこに書くキーはテンプレート向けに意図したパラメータ名なので、各キーはソースのいずれかのテンプレートが宣言するパラメータを指定する必要があります。どのパラメータも指定しないキーはビルドを停止させ、そのキーと各テンプレートが実際に宣言しているパラメータを示します。これは CloudFormation が未知のパラメータについて報告するはずの失敗を、まだ自分で修正できる段階で報告するものです。valuesMapping を宣言しない Recipe または FeatureRecipe は何も埋めません。component やアタッチメント自身の値は、その他の入力向けに書かれた独自の名前のままプロバイダに届き、読まれずに残ります。

値の種類によって、テンプレートに届くものが決まります。

  • リテラル(文字列、数値、ブール値、またはそれらのリスト)はテンプレートに書き込まれ、スタックのデプロイ時にパラメータの Type に対して同じ値が渡された場合に CloudFormation が行うのと同じ方法で変換されます。Number は、それへの Ref が返す文字列になるため、7 は "7" として届きます。CommaDelimitedList または List<…> 型は文字列のリストになり、リストか、各要素がトリムされるカンマ区切りの文字列のいずれかを受け取ります。それ以外の型はすべて 1 つの文字列を受け取ります。リテラルはパラメータ自身の AllowedValues、AllowedPattern、MinLength、MaxLength、MinValue、MaxValue に照らしてチェックされ、それらが拒否するリテラルはビルドを停止させ、パラメータと制約を示します。そのため、パラメータを埋めても、テンプレートが宣言したチェックが失われることはありません。ビルドが読み取れない正規表現構文で書かれたパターンは、スタックのデプロイ時に CloudFormation がチェックするために残されます。
  • 全体が 1 つの CloudFormation 組み込み関数である値は、スタックのデプロイ時に CloudFormation が評価するために、その組み込み関数のまま参照箇所に届きます。{"Fn::GetAtt": [Queue, Arn]} のような長い形式のマッピング、またはちょうど 1 つの短い形式である文字列(!GetAtt Queue.Arn、!Ref Bucket、!Sub …、および CloudFormation が定義するその他の形式)がこれに当たります。別の component が公開した参照は、この方法でパラメータに届きます。カタログの CloudFormation Recipes はそのような参照を短い形式のテキストとして公開し、それをインジェクションコンテキストから読み取る valuesMapping がそれを引き渡します。埋め込んだ参照は、引用符で囲んでも囲まなくても同じように読まれます。引用符で囲むと("{{ .context.inject.env.BUCKET_NAME }}")、マッピングは文字列 !GetAtt Queue.Arn を引き渡します。囲まない場合、マッピング自身の YAML は !GetAtt Queue.Arn をタグとして読みますが、タグは破棄されずに引数とともに保持されます。どちらも組み込み関数としてパラメータに届きます。感嘆符で始まるだけの値や、CloudFormation の短い形式を指定しない値は、テキストのままです。
  • 動的参照({{resolve:ssm:…}}、{{resolve:ssm-secure:…}}、または {{resolve:secretsmanager:…}})は、スタックのデプロイ時に CloudFormation が解決するために、書かれたとおりに参照箇所に届きます。そのため、それが指定する値がテンプレートに含まれることはありません。
  • 別の component が別のスタックから公開する値は、フラグメントが受け取るのと同じ Fn::ImportValue または Fn::GetStackOutput というスタック間参照として(スタック間の接続を参照)、テンプレートがパラメータを参照していたすべての箇所に届きます。

CloudFormation が Parameter Store から読み取る型(AWS::SSM::Parameter::Value<…>)のパラメータには、CloudFormation がそれに対して行う処理を再現するリテラルがないため、そのようなパラメータにバインドされたリテラルはビルドを停止させます。{{resolve:ssm:…}} 参照か組み込み関数をバインドするか、バインドしないままにしてください。テンプレートが Fn::Sub の変数として指定するパラメータにバインドされたリストもビルドを停止させます。変数は 1 つの文字列を置換するためです。valuesMapping が null に設定したキーも、パラメータを示してビルドを停止させます。パラメータは値を受け取るものであり、null は値ではないためです。スタックのデプロイ時に渡される値またはその Default のためにパラメータを残すには、そのキーをマッピングから省いてください。

名前でパラメータを読み取るルールがあると、そのパラメータはバインドされないままになります。 テンプレートの Rules 内の Fn::ValueOf は、宣言されたパラメータを Ref を通じてではなく論理 ID で指定します。パラメータを埋めるとその宣言が取り除かれるため、ルールがそのように読み取るパラメータをバインドするとビルドは停止し、ルールとパラメータを示します。

シークレットを含む可能性のあるリテラルは拒否され、組み込み関数は指定されたとおりに書き込まれます。 テンプレートに書き込まれた値は、スタックのテンプレートを読み取れる誰もが読み取れます。

  • テンプレートが NoEcho と宣言するパラメータは動的参照または組み込み関数を受け取り、それにバインドされたリテラルはビルドを停止させます。
  • 作成者が機密と宣言した値を valuesMapping が読み取る場合、その出力のどれについても元の値まで遡ることはできないため、それがバインドするすべてのリテラルはビルドを停止させます。それがバインドする動的参照と組み込み関数は、組み込み関数内のテキストも含めて、指定されたとおりに書き込まれます。したがって、たとえばマッピングが Fn::Sub のテキストに埋め込んだシークレットは、そのテキストとしてテンプレートに届きます。シークレットそのものをテンプレートから除外できるのは動的参照だけです。そのようなビルドが続行される場合、Recipe のマッピングでも、component にアタッチされた Feature の FeatureRecipe のマッピングでも同様に、宣言されたリーフごとに 1 つの注意を出力し、そのリーフとマッピングを持つエンティティを示します。A declared-sensitive value reaches the target through a values mapping(機密と宣言された値が values mapping を通じてターゲットに届く)を参照してください。
  • 動的参照は、そのパラメータがリソースの UserData プロパティ、AWS::CloudFormation::Init メタデータ、または Outputs で参照されている場合にビルドを停止します。CloudFormation は EC2 のユーザーデータやそのメタデータ内の動的参照を解決せず、また Outputs はスタックを読むすべての人に表示されるためです。

このような拒否はいずれもパラメータを名指ししますが、値は一切引用しません。

ソースから取得したテンプレートからリソースを除外する

ソースから取得したテンプレートのリソースはそのテンプレート自身のものです。値はテンプレートが宣言するパラメータを通じてのみ届くため、Release が作成してはならないリソース(オペレーターがすでに用意しているバケットや、プラットフォームが別の場所で管理しているキーなど)を宣言する、git リポジトリから取得したテンプレートは、値によって変更できません。そのためにあるのが、Recipe または FeatureRecipe の omits: エントリです。この Provider は、ソースから取得したテンプレートに対してのみこれを適用し、それ以外には適用しません。artifacts: エントリが記述するフラグメントは、これを適用せずにレンダリングされます。

spec:
capability: cloudformation
implements: core/store:1.0.0
source:
kind: git-repository
url: https://git.example.com/platform/templates.git
ref: v3.2.0
module_subdir: store
omits:
# The template bundles an access-log bucket; this Release logs elsewhere.
- kind: AWS::S3::Bucket
name: StoreLogs

エントリは、1 つのリソースをその Type と論理 ID で指定します。 エントリの kind はリソースの Type(AWS::S3::Bucket など)であり、name はリソースの論理 ID、つまり Resources の下のキーです。どちらも記述どおりに厳密に比較され、両方が一致する必要があります。そのため、Type が正しくても論理 ID が一致しないエントリは何も除外しません。テンプレートには名前空間がないため、namespace を持つエントリは、コンポーネントのレンダリング時にそのエントリを示してビルドを停止します。何かが除外される前に、すべてのエントリが検査されます。

ソースのすべてのテンプレートが照合されます。 単一ファイルのソースにはテンプレートが 1 つあります。ディレクトリソース(git リポジトリから取得したソースは常にこれです)には、.yaml、.yml、.json、.template で終わるすべてのファイルが含まれ、エントリはそのいずれかで指定されたすべてのリソースを除外します。テンプレートと一緒に含まれるその他のファイルは読み込まれません。Provider は、各エントリがそれらすべてを通じて除外したリソースの数を報告し、何も除外しなかったエントリはビルドを停止します。An omits entry left out nothing the source rendered(omits エントリがソースのレンダリング結果から何も除外しませんでした) を参照してください。

除外されたリソースは、テンプレートが他の何かに読まれる前に取り除かれます。 来歴情報は付与されず、スタックが持つ名前としても数えられません(そのため、別のコンポーネントが同じ論理 ID でリソースを提供しても両者は衝突しません)。また、組み立てられたスタックに到達することもありません。テンプレートのそれ以外の部分は、そのリソースなしで記述された場合とまったく同じように書き出され、すべてのリソースが除外されたテンプレートには空の Resources セクションが残ります。

除外されたリソースは、残った部分から参照されたままであってはなりません。 CloudFormation は、宣言していないリソースを参照するテンプレートを拒否するためです。リソースが削除された後、残りのテンプレートがそれらのいずれかに対してまだ行っている参照はすべてビルドを停止し、メッセージにはテンプレート、リソース、参照がそのリソースをどのように指定しているか、そして参照の位置をテンプレートのルートからのパス(たとえば /Resources/Store/Properties/LoggingConfiguration/DestinationBucketName)で示します。参照とは、CloudFormation のテンプレートリファレンスが論理 ID によってリソースを指定するものとして定義しているもので、すべてのリソースの本体(プロパティ、メタデータ、ポリシーを含む)とすべての出力で読み取られます。

  • 論理 ID を引数とする Ref。
  • 最初の要素が論理 ID であるリスト、または最初のドットより前のテキストが論理 ID である 1 つの文字列(!GetAtt StoreLogs.Arn)としての Fn::GetAtt。
  • 1 つの論理 ID またはそのリストとしての、リソースの DependsOn。
  • 文字列形式とリスト形式の両方における Fn::Sub の各変数。${StoreLogs} と ${StoreLogs.Arn} はどちらも StoreLogs を指定します。

参照のように見えるだけで、参照としては読み取られない値もあります。${!StoreLogs} はリテラルテキストであり、リスト形式のマップが名前を付ける変数はそのマップの値です。リソースの Condition と Fn::If の最初の引数は条件を、Fn::FindInMap はマッピングを、Fn::ImportValue は別のスタックのエクスポートを、Fn::GetAZs はリージョンを指定します。Conditions、Mappings、Parameters、Rules の各セクションはリソースを指定できず、テンプレート自身のトップレベルの Metadata セクションは CloudFormation が読み取るのではなく保存する情報であるため、いずれも検査されません。論理 ID 自体が組み込み関数として記述された Ref または Fn::GetAtt は、スタックのデプロイ時にそれを解決する AWS::LanguageExtensions 変換の下でのみ有効です(Top-level sections in the assembled stack を参照)。そのため、検査が読み取れるリソースを指定しておらず、そのまま残されます。ソースが一度も宣言していないリソースへの参照も同様です。

検査は、宣言している Recipe または FeatureRecipe 自身のテンプレートをまとめて読み取ります。 それらは 1 つのスタックに組み立てられるため、それらのテンプレートのうち別のものがまだ宣言している論理 ID への参照は停止されません。それ以外は読み取られません。除外されたリソースへの参照は、別のコンポーネントがその論理 ID のリソースを宣言している場合でもビルドを停止し、スタックに組み立てられる他のもの(別のコンポーネント、アタッチされた Feature、または Recipe 自身の artifacts: エントリ)による参照はこの検査の対象外であるため、デプロイ時に CloudFormation がスタックを拒否します。参照を残すには、リソースを残してください。パラメータに結び付けられた値はそのパラメータへの参照だけを置き換えるため、リソースへの参照はテンプレート自身のものであり、値によって変更することはできません。参照しているリソースも除外するか、エントリを削除してください。出力はリソースではなく、エントリが出力を指定することもないため、テンプレートの Outputs が参照するリソースはテンプレートから除外できません。除外するとビルドが停止します。

クラウドターゲットのアノテーション

3 つのバウンダリアノテーションは、スタックのデプロイ先を provider に伝え、provider がスタック間参照を正しく接続できるようにします。

  • aggrega.ai/aws-account — スタックのデプロイ先となる AWS アカウント。
  • aggrega.ai/aws-region — スタックのデプロイ先となる AWS リージョン。
  • aggrega.ai/aws-assume-role-arn — アカウント間のスタック読み取りが、ピアスタックのエクスポート値に到達するために引き受ける IAM ロールの ARN。

これらのアノテーションはコンパイラにとって不透明です。コンパイラはその値を解釈せずに provider へそのまま渡します(well-known-annotations.md を参照)。これらは producer 側のバウンダリ、つまりエクスポート値を所有するスタックに記述します。アカウント間の読み取りは producer のアカウントへロールを引き受けて入るため、その読み取りを記述するアカウント、リージョン、ロールはすべて consumer ではなく producer バウンダリのアノテーションから取得されます。

スタック内参照

uses エッジが同じバウンダリ(同じスタック)に配置される 2 つのコンポーネントを接続する場合、消費される値は、1 つのテンプレート内でプロデューサーリソースの論理 ID に対する Fn::GetAtt として接続されます。プロデューサーの provides の値は、ネイティブなスタック内参照としてコンシューマーのレンダリングされた入力に渡されます。エクスポートやインポートは必要ありません。コンシューマーのフラグメントは、このような値をそのまま Value: {{ .context.inject.env.DB_HOST }} と書くことも、引用符の中に Value: "{{ .context.inject.env.DB_HOST }}" と書くこともできます。どちらの場合もテンプレートは !GetAtt Db.Endpoint.Address を組み込み関数として読み取ります。ちょうど 1 つの短縮形である文字列は、valuesMapping の中と同様にフラグメントの中でも、その組み込み関数としてスタックに届くためです。aws-rds-and-ecs-service の例では、1 つのスタック内で Amazon ECS のタスク定義が RDS インスタンスのアドレスを読み取る形でこれを示しています。

スタック間の接続

uses エッジがある境界から別の境界へまたがる場合、つまり 2 つのコンポーネントが異なるスタックに組み立てられる場合、参照を単純な値にすることはできません。生成される値は、プロデューサースタックがデプロイされるまで存在しないためです。プロバイダーはこれを CloudFormation のクロススタック参照として接続します。プロデューサースタックは、決定的なエクスポート名(リリース、境界、コンポーネント、提供キーから導出されます)のもとで、値を Export 付きのスタック Output として公開します。コンシューマースタックは、2 つの境界が宣言する配置を比較して選ばれる、次の 2 つの組み込み関数のいずれかでそれを読み取ります。

  • Fn::ImportValue — 同一アカウント・同一リージョンの場合です。CloudFormation は、アカウントとリージョン内で一致するエクスポート名に対してインポートを解決します。
  • Fn::GetStackOutput — 実際のクロスアカウントまたはクロスリージョンの読み取りです。コンシューマーは、プロデューサー境界の aws-assume-role-arn を引き受けてプロデューサーのアカウントとリージョンに入り、プロデューサースタックの出力を直接読み取ります。

検出のセマンティクス。 プロバイダーが Fn::GetStackOutput を使うのは、両方のエンドポイントが配置(アカウント/リージョン)を宣言し、かつそれらの配置が異なる場合だけです。それ以外のすべての場合、つまりどちらも宣言しない、一方だけが宣言する、または両方が同じ配置を宣言する場合は、Fn::ImportValue を使います。これは保守的な規則です。同一アカウントのクロススタック読み取りは単純なインポートのままとし、直接読み取りの組み込み関数は実際のクロスアカウントまたはクロスリージョンの移動にのみ使います。

特定のコンシューマーが Fn::GetStackOutput を通じてクロスアカウントで読み取る場合でも、プロデューサースタックは常に Export を公開します。使われないエクスポートは何の影響も及ぼさず、無条件に公開することで、各コンシューマーが値をどう読み取るかからプロデューサーのテンプレートが独立した状態に保たれます。

1 つの値の複数のコンシューマーは 1 つのエクスポートを読み取ります。 複数のコンポーネントが境界をまたいで同じ提供値を読み取る場合、つまり 1 つのスタック内の 2 つのコンシューマー、または複数のスタックにあるコンシューマーの場合、プロデューサースタックはその値の Export を 1 回だけ公開し、すべてのコンシューマーがその 1 つの名前を読み取ります。各 Fn::ImportValue は同じエクスポートをインポートし、別のアカウントまたはリージョンに配置されたコンシューマーは Fn::GetStackOutput を通じて同じ出力を読み取ります。他のどのコンシューマーも読み取らない値をあわせて読み取るコンシューマーは、その値のエクスポートだけを追加します。

aws-rds-and-ecs-service の例は同一アカウントの場合を構築しています。RDS インスタンスのスタックはサーバーのエッジが消費する各エントリをエクスポートし、サーバーのスタックはそれぞれを Fn::ImportValue で読み戻します。

バージョンに関する注意。 Fn::GetStackOutput は CloudFormation のネイティブな組み込み関数です。これを使ってレンダリングされたクロスアカウント参照には、この組み込み関数を認識する CloudFormation ツールが必要です。同一アカウントの経路では、どこでも利用できる Fn::ImportValue を使います。

注入されるのではなく接続から読み取られる値

コンシューマーの Recipe は、接続の inject ブロックを通じて受け取る代わりに、.context.uses.<alias>.provides を通じてプロデューサーの値を接続から直接読み取ることができます。スタックの境界をまたぐ場合、このような読み取りは注入された値と同じ方法で接続されます。

  • CloudFormation の組み込み関数である値(!GetAtt Db.Endpoint.Address のような短縮形のタグ、または長形式の Ref や Fn:: マッピング)は、プロデューサーのスタックだけが宣言するものを指すため、コンシューマーは注入された値と同じクロススタック参照を受け取ります。プロデューサースタックはそのキーの Export を公開し、コンシューマーはそれを Fn::ImportValue で読み取ります。2 つのバウンダリが異なる配置を宣言している場合は Fn::GetStackOutput で読み取ります。
  • プレーンテキストである値(ポート、プロトコル、データベース名)は、どちらのスタックでも同じ意味を持つため、コンシューマーは値そのものを受け取り、その値のためのエクスポートは公開されません。値は CloudFormation が読み取る形で配置されます。全体として書かれた値はバウンダリがない場合と同じようにレンダリングされ、引用符の中に書かれた数値の形の値は数値として配置されます。

値が組み込み関数かどうかは、このプロバイダが、プロデューサー自身の provides ブロックを読むのと同じ方法で値を読んで判定します。コンパイラは、プロデューサーの Recipe が書いたとおりに値を渡し、それを解釈しません。

テンプレートはこのような値をコピーすることしかできません。 値を全体として書くことも、より長い文字列の中に書くことも、quote のように値をそのまま残す関数に渡すこともできます。比較、分岐、長さ、または値を変更する関数(eq、if、len、upper)は、値以外のものに対して判定されてしまいます。このような接続では、テンプレートに渡されるのは、両方のスタックがアセンブルされた後にプロバイダが置き換える代替値だからです。そのためビルドは停止し、テンプレートとそれが読み取った各値を、読み取り元の接続と両端のコンポーネントとともに示します。分岐には、消費側コンポーネント自身の値を使ってください。アタッチされた FeatureRecipe の injectMapping や、バウンダリの接続を読み取るバウンダリスコープの FeatureRecipe にも同じことが当てはまります。より長い文字列の中に書かれた値は、プロバイダ自身の制限にも当たります。クロススタック参照は値全体としてしか成り立たないため、より長い文字列の中に書かれた組み込み関数は、注入された値の場合と同様にビルドを停止させます。

エクスポート名の構築方法

4 つの部分は二重ハイフンで連結され、各部分はエクスポート名を構成する英字、数字、ハイフンで書き表されます。英字と数字はそのまま引き継がれ、部分内のハイフンも同様です。payments-db は payments-db のままです。それ以外の文字は -z で始まる短いエスケープとして書かれます。スラッシュは -zs、アンダースコアは -zu、ドットは -zd です。値がまったくない部分は -ze と書かれます。スタック名も、リリースと境界から同じ方法で構築されます。

したがって、リリース orders の、dist/ 配下の出力ディレクトリが stack-a/cloudformation である境界にあるコンポーネント db から host を公開するエクスポートは次のとおりです。

aggrega--orders--stack-a-zscloudformation--db--host

逆に読み解くことは一意に可能であり、それは付随的な利点ではなく目的そのものです。部分には連続する 2 つのハイフンが含まれず、ハイフンで終わることもないため、二重ハイフンは常に連結箇所です。したがって、異なる部分の組は常に異なる名前を生成します。payments-db と payments_db は 1 つに収束せず別々のエクスポートになり、ある部分の端のハイフンが隣の部分に属するものと読まれることはありません。

エクスポート名が何に対して一意であり、それがどこで終わるか

1 回のビルド内では、エクスポート名はリリース、境界、コンポーネント、提供キーのちょうど 1 つの組を識別します。どの 2 つも 1 つの名前に収束しないため、ビルドがあるエクスポート値を別の値の陰で失うことはありません。

CloudFormation はさらに、スタックが配置されるアカウントとリージョンに既にデプロイされているすべてのものにわたって、エクスポート名が一意であることを要求します。これはビルドではなくデプロイの性質であり、ビルド時のどのような導出も届かない範囲にあります。コンパイラは AWS に対して認証せず、AWS に問い合わせず、別のビルドの出力を読むこともできないため、事前に計算されたものが、そこに既にデプロイされているものを観測することはできません。

その境界線を越えて区別を保つのは、すべてのエクスポート名とスタック名の先頭にあるリリースの識別子です。アカウントとリージョンを共有する 2 つのデプロイは、異なる名前でリリースされることでエクスポートを分離します。これが利用者の手にある手段であり、リリースの識別子が名前の末尾ではなく先頭に置かれる理由です。

Outputs のエントリは独自のエクスポート名を宣言できる

Recipe の Outputs: ブロックは作成者が記述した CloudFormation であり、その中のエントリは Name: を持つ独自の Export: を持つことができます。その名前は書かれたとおりに組み立て後のスタックに届きます。プロバイダーはそれを書き換えず、接頭辞も付けず、導出された名前のような形であることも要求しません。

通常、これについてそれ以上述べることはありません。プロバイダーが導出するどの名前とも一致しない作成者記述のエクスポート名は、導出された名前と並んで公開され、言及されることはありません。作成者による記述はサポートされています。サポートされないのは 1 つの一致だけです。

作成者記述のエクスポート名が、同じビルド内の境界をまたぐリンクに対してプロバイダーが導出する名前と等しい場合、ビルドは停止します。 両方の宣言が組み立て後のテンプレートに届き、1 つのスタックで 1 つのエクスポート名が 2 回宣言されることになります。エクスポート名は一意でなければならないため、両方を成立させることはできません。停止時には、導出されたエクスポート名とその構築元の 4 つの部分が示されるため、どのリンクがそれを生成したかを確認できます。また、作成者記述の宣言が置かれているスタック出力の名前も、Recipe が書いた名前ではなくプロバイダーが組み立てる名前であることを示したうえで表示されます。Recipes で検索すべき語はエクスポート名です。 作成者記述のエントリは停止メッセージとまったく同じ綴りでそれを記述しています。この同一性こそが 2 つを衝突させるものです。したがって、それはメッセージと自分のファイルの両方に現れる唯一の文字列です。そのエントリが宣言するエクスポート名を変更すれば停止は解消され、そのエントリの Export: ブロックを削除してクロススタック接続にエクスポート自体を公開させても解消されます。

このチェックはビルド範囲のものであり、その範囲は 1 つのスタックです。 組み立て後のスタックが宣言するエクスポート名を、同じスタックに公開する境界をまたぐリンクに対してプロバイダーが導出する名前と比較します。これは、ビルドが組み立てたものから行える比較です。2 つのスタック同士は比較されません。また、作成者記述の名前が、アカウントとリージョンに既にデプロイされているエクスポートの中で何と出会うかはデプロイの性質であり、エクスポート名が何に対して一意であり、それがどこで終わるかで述べた理由により、ビルド時のどのような導出も届かない範囲にあります。コンパイラは AWS に対して認証せず、AWS に問い合わせず、別のビルドの出力を読むこともできません。単純な文字列ではなく組み込み関数として書かれたエクスポート名も、同じ境界線の向こう側にあります。それはデプロイ時に解決され、ここでは組み込み関数を評価しないため、ビルドが比較する名前が存在しません。

境界をまたぐリンクが公開先とする出力に、そのリンクが書いていない Export が既に付いている場合も、ビルドは停止します。 その出力は、コンシューマーが読み取る提供キーに対してプロバイダーが組み立てるものです。そのため、Outputs: ブロックで同じキーのもとに独自の Export: を持つエントリを書く Recipe は、リンクのエクスポートが置かれるまさにその場所に自身のエクスポートを置くことになります。そのエクスポートの名前がプロバイダーの導出する名前とまったく同じである場合は、それがリンク自身のエクスポートとなり、すべてのコンシューマーがそれをインポートします。そうでない限り、両方をそこに成立させることはできません。リンクのエクスポートを書けば作成者のものが上書きされ、作成者のものを残せば、すべてのコンシューマーがリンクの公開していない名前をインポートすることになります。停止時には、導出されたエクスポート名とその構築元の 4 つの部分が示され、その出力で見つかったものが示されます。つまり、エントリが宣言するエクスポート名、組み込み関数として書かれた名前、何も名前を指定しない Export: ブロック、またはブロックではなく単純な値として書かれた Export: のいずれかです。そのエントリの Export: ブロックを削除すれば停止は解消され、その後はクロススタック接続が、すべてのコンシューマーがインポートするエクスポートを公開します。

デプロイの順序付け

Release の boundary の syncWave: の値は、その boundary が組み立てられるスタックのプロビジョニングの順序を決めます。boundary 内のすべての component はその boundary の wave を継承します。複数の boundary が同じ出力ディレクトリに解決され、それらのフラグメントが 1 つのテンプレートに組み立てられる場合、スタックは複数の wave を持ち、provider はそれらの間の順序を DependsOn として表現します。

各リソースは、リソースを 1 つ以上持つ直前のウェーブのすべてのリソースを指定し、それより前のウェーブは指定しません。 残りは CloudFormation が連鎖させます。ウェーブ 2 のリソースはウェーブ 1 に依存し、そのウェーブはさらにウェーブ 0 に依存するため、各リソース自身のリストはスタック全体ではなく 1 つのウェーブ分の大きさに収まったまま、シーケンス全体が順序付けられます。ウェーブは連続している必要はなく、負の値もごく普通に使えます。スタックの他の部分が読み取るバケットやロールには -1 がよく選ばれます。最も低いウェーブは何も指定しません。それより前にあるものが存在しないためです。

この順序が意味するのは、作成順序と、その逆の削除順序です。 CloudFormation は可能な範囲でリソースを並列に操作し、DependsOn はその並列性を上書きして、指定されたリソースを決められた順序で操作させます。この属性は両方向に作用するため、リソースを先に作成する wave は、そのリソースを後で削除します。正しい破棄の順序は、他に何も必要とせず、この順序付けに伴って得られます。

これは準備完了の順序付けではありません。 スタックテンプレートにはリソースが利用可能であるという概念がないため、ここではリソースが準備完了になるのを待つことはなく、CloudFormation がその作成を終えるのを待つだけです。これは compose での同じ wave とは実際に異なる点です。compose では healthcheck を宣言したサービスは healthy を報告するまで待機されます。compose には待機の基準となる準備完了のプリミティブがあり、スタックテンプレートにはありません。このターゲットが提供するのは作成順序であり、それを率直に述べるほうが、果たせない約束に注意書きを添えるよりも有用です。

記述された DependsOn は拡張され、置き換えられることはありません。 独自の順序制約を宣言したフラグメントはそれを保持します。記述したエントリが記述した順序のまま先頭に残り、その後に wave のエントリが続きます。両方の要件が成り立ち、どちらももう一方を隠しません。単一の論理 ID とリストのどちらも読み取られ、マージされた値はリストとして出力されます。リストは、マージで生じるエントリの数にかかわらず成り立つ唯一の書き方です。

すべてのリソースが 1 つの wave を持つスタックには、これによる影響はありません。 syncWave をまったく宣言しない Release も同様です。すべての寄与元はこのフィールドのデフォルト値 0 を持ち、組み立てられたテンプレートは単一の wave を持ち、出力は provider が wave の順序付けを表現しなかった場合とまったく同じになります。

2 つのスタックにまたがる順序付けは表現できず、近似もされません。 DependsOn は同じテンプレート内のリソースを指定するものであり、別のスタックに組み立てられる component はその外にあります。そのため wave は、組み立て先のスタック内のすべてのリソースを順序付けますが、その外には及びません。2 つのスタックの順序付けはオペレーターの関心事です。スタック間参照がビルド時ではなくデプロイ時に解決されるのと同じです。

wave が表現しない順序付けは CloudFormation 自身の関心事として残り、その多くはリソース間の参照がすでに担っています。producer のリソースに対する Fn::GetAtt は、そのリソースを先に作成するよう CloudFormation に伝えます。参照からも wave からも導かれない制約を必要とするフラグメントは、自ら DependsOn を記述します。これが上記のマージで保持されるケースです。

決定性

同じ入力が与えられると、provider は実行ごとにバイト単位で同一のスタックテンプレートを出力します。論理 ID、出力キー、エクスポート名、リソースの順序はすべて決定的であるため、CloudFormation のスタックテンプレートは GitOps のレビューで差分がきれいに表示されます。