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

アタッチメントを持つ CloudFormation スタック

マネージドデータベースと、それを読み取るアプリケーションを、開発者の意図として一度だけ記述し、AWS CloudFormation のスタックテンプレートに組み立てます。2 つのアタッチメントが独自のリソースを持ち込む(データベース上のアラームと、境界上の共有設定パラメータ)ため、この例では、アタッチメントのリソースが組み立てられたスタックのどこに配置され、コンポーネントのリソースと並んでどのように命名されるかを示します。

同じ開発者の意図を 3 通りの方法でビルドします。1 つのスタックとして、スタック間をまたぐ参照を持つ 2 つのスタックとして、そして意図的に、停止するビルドとしてです。

このページの出力ブロックは、これらのページの出力の読み方に従い、実際の実行からコピーしたものです。

ファイル

  • aggregate.yaml — 開発者の意図です。型が core/datastore/mariadb のデータベース payments-db と、型が example/compute/db-reader で、そのデータベースを使用することを宣言する reporting-app を定義します。AWS に関する記述はここにはありません。データベースの features: ブロックには storage-headroom があり、 example/storage-alarm をアタッチします。
  • release-one-stack.yaml — 両方のコンポーネントを 1 つの境界に置くため、両方が 単一のスタックにアセンブルされます。境界全体に core/shared-config をアタッチします。
  • release-two-stacks.yaml — 同じ意図を 2 つの境界に分割するため、 アプリケーションからデータベースへの参照がスタックの境目をまたぎます。
  • release-negative-name-collision.yaml と aggregate-name-collision.yaml — 失敗することが想定されています。 1 つのコンポーネントにアラームを 2 回アタッチします。
  • manifest.yaml — 各コンポーネント型と、アタッチされた各 Feature を、 このターゲットでそれを実装する Recipe にバインドします。
  • .aggrega-config.yaml — カタログのエンティティの解決元となるハブレジストリを指定します。

どのリリースも、payments-db のエントリでデータベースの root_password スロットを core/generated-secret にバインドします。このターゲットでは管理者パスワードを RDS が所有し、Manifest が選ぶデータベースの Recipe にはそのことを示すディレクティブがあります。そのため、このバインドは Release に記述するオペレーターの判断であり、Aggregate はこれについて何も述べません。

どのリリースも core/backup を infra.retention_days: 14 付きで payments-db にアタッチし、Manifest はそれを cloudformation/backup-native にバインドします。RDS は、特に指定がなければインスタンスの自動バックアップを 7 日間保持しますが、このアタッチメントはそれぞれを 14 日間保持します。FeatureRecipe は何もレンダリングしません。バックアップはインスタンスの設定であるため、データベースの Recipe がアタッチメントを読み取り、"BackupRetentionPeriod": 14 をインスタンス自身の Properties に書き込みます。

この例で使用するエンティティはすべて公開カタログにあります。リリースファイルの横に コピーしたものはないため、この例はカタログの非公開スナップショットではなく、 現状のカタログに対して解決されます。

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example cloudformation-rds-stack

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd cloudformation-rds-stack

ビルド

この例には 3 つの release が含まれているため、ビルドしたいものを指定してください。1 回の実行でビルドされる release は 1 つです。各 release の最初のビルドにはロックファイルが必要で、それは pull が書き込みます。

Terminal window
aggrega pull --release release-one-stack.yaml
aggrega build --release release-one-stack.yaml

ビルドは次のように出力します。<workspace> はこの例のフォルダを表します。

Total build time: 4.1s
Build completed: 1 file written to <workspace>/dist

組み立てられたスタックは dist/one-stack/cloudformation/cloudformation-stack.json に出力されます。そのディレクトリにレンダリングされるすべての component とすべてのアタッチメントが、その 1 つのテンプレートに寄与します。 provider は寄与元ごとにファイルを出力するのではなく、純粋な JSON の単一スタックを出力します。

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、自分ではフォルダーを作成しないでください。ワークスペースフォルダーにまだ `cloudformation-rds-stack` フォルダーがない場合は、`example` を `cloudformation-rds-stack` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `cloudformation-rds-stack` フォルダーに書き込まれます。次に、`workspace_root` を `cloudformation-rds-stack`、`release` を `release-one-stack.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き込んだファイルを教えてください。それらは `cloudformation-rds-stack/dist/` の下にあります。

何が出力され、誰がそれを寄与したか

one-stack ビルドは、4 つの異なる寄与元から4 つのリソースを組み立てます。

リソース寄与元
PaymentsDbデータベースコンポーネント自身の Recipe
PaymentsDbStorageHeadroomそのコンポーネント上の storage-headroom アタッチメント
AppSharedConfig境界上の shared-settings アタッチメント
ReportingAppアプリケーションコンポーネント自身の Recipe

payments-db 上の backup アタッチメントが表にないのは、独自のリソースを提供しないためです。それが設定する内容は PaymentsDb の内部に入ります。

各リソースは寄与元を示す来歴ブロックを持つため、両者が寄与したスタックの中でも 2 つの部分を区別できます。

"PaymentsDbStorageHeadroom": {
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/aggregate-name": "aggregate",
"aggrega.ai/boundary-path": "app",
[… omitted: a compiler-version entry, which moves with the build]
"aggrega.ai/component-id": "cfr--payments-db--storage-headroom",
"aggrega.ai/environment": "production",
"aggrega.ai/provider": "cloudformation",
[… omitted: a provider-version entry, which moves with the build]
"aggrega.ai/recipe-uri": "storage-alarm:1.0.0"
}
},
[… omitted: the alarm's Properties, printed in full just below]
"Type": "AWS::CloudWatch::Alarm"
},

2 つのバージョンエントリは、このブロックの中でビルドごとに変わる唯一の行であるため省略しています。3 つ目の省略はアラームの Properties だけで、これは下で個別に示します。表示されている内容はすべて、ご自身のビルドが書き出すものと同じです。

アラームはデータベースではなくアタッチメントのリソースです。Aggregate から storage-headroom を外すと、そのリソースとそれが公開する 1 つの出力だけが削除され、PaymentsDb はバイト単位で元のまま残ります。

アタッチメントのリソース名は、そのアタッチメントを持つスコープを含む

Feature は一度作成されて何度もアタッチされるため、FeatureRecipe が導出する名前はアタッチメントごとに一意である必要があります。この FeatureRecipe はホストコンポーネントとアタッチメント名を組み合わせます。ホスト payments-db を storage-headroom の下で持つと、PaymentsDbStorageHeadroom になります。

ホストだけを組み合わせれば、アラームを監視対象のリソースと区別するには十分ですが、同じ Feature を 1 つのコンポーネントに 2 回アタッチした場合の自己衝突を防ぐには十分ではありません。下の失敗するリリースはまさにこの点を扱っています。

アラーム自身のプロパティは、ホストの導出名でホストを参照します。

"Properties": {
"AlarmDescription": "Free storage below 21474836480 bytes on payments-db",
"ComparisonOperator": "LessThanThreshold",
"Dimensions": [
{
"Name": "DBInstanceIdentifier",
"Value": {
"Ref": "PaymentsDb"
}
}
],
"EvaluationPeriods": 2,
"MetricName": "FreeStorageSpace",
"Namespace": "AWS/RDS",
"Period": 300,
"Statistic": "Minimum",
"Threshold": 21474836480,
"TreatMissingData": "breaching"
},

データベースリソースに対する Ref は、スタックのデプロイ時にそのインスタンスの識別子に解決されます。両方の部分が同じコンポーネント名から PaymentsDb を導出するため一致するのであり、ここでは何も検索されません。

1 つのアタッチメントで、誰が何を決めるか

アタッチメントは、コンポーネントと同じように入力を分けます。アプリケーションが必要とするヘッドルームの量は開発者の意図であり、aggregate.yaml のアタッチメント上に記述されます。これはアプリケーションの性質です。アラームの通知先と、発報までに低下がどれだけ続く必要があるかはオペレーターのサイジングであり、Release から指定されます。

payments-db:
features:
storage-headroom:
infra:
evaluation_periods: 3
notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"

Release は、Aggregate が宣言したアタッチメントに対して infra を指定し、values は決して指定しません。two-stack リリースは両方を設定し、one-stack リリースはどちらも設定しません。その違いは出力から読み取れます。設定した場合:

"Properties": {
"AlarmActions": [
"arn:aws:sns:eu-west-1:123456789012:payments-oncall"
],

設定しない場合、フィールドは空ではなく存在しません。アラームは通知アクションをまったく持たずに出力され、EvaluationPeriods は Feature が宣言したものではなく Recipe が持つ 2 になります。どちらも指定しない Release でも動作するアラームが得られ、一方を指定するとちょうど 1 つのフィールドが追加されます。

アタッチメントの出力は、自身ではなくホストによって命名される

スタックの 2 つの部分は異なる規則で命名され、こちらが驚かれやすい方です。

リソースの論理 ID はアタッチメント自身の Recipe から来ます。上記の名前がそれです。出力は公開するコンポーネントとエントリを合わせて命名され、アタッチメントの場合、公開するコンポーネントはホストです。 アラームは 1 つのエントリ alarm-id を公開し、次のように現れます。

"paymentsXzhdbXXalarmXzhid": {
"Value": {
"Ref": "PaymentsDbStorageHeadroom"
}
},

規則がわかれば 2 つの部分は読み取れます。論理 ID は英字と数字しか許さないため、プロバイダーはその文字集合が受け付けないものを削除せずに綴り出します。Xzh は記述したハイフンで、XX はコンポーネント名が終わりエントリ名が始まる位置です。payments-db が alarm-id を公開する場合にのみ、この名前になります。組み立てられたスタック内の名前で方式の全体を説明しています。

これは、データベース自身が alarm-id を公開した場合と同じ出力名です。そのため、ホストも公開するエントリ名は、アタッチメントのものと 1 つの出力名で衝突します。アタッチメント固有と読めるエントリ名にすることで、ホストのものと区別できるのはこのためです。

境界全体のアタッチメントは境界に対して一度だけレンダリングされる

core/shared-config は Release で、コンポーネントではなく境界上にアタッチされ、その境界に対して一度だけレンダリングされます。境界内のコンポーネントごとに一度ではありません。one-stack ビルドには 2 つのコンポーネントと、ちょうど 1 つの AppSharedConfig が含まれます。

"AppSharedConfig": {
[… omitted: the provenance Metadata, whose shape is shown above]
"Properties": {
"Description": "Settings shared by every component in the app boundary",
"Name": "/app/shared-config",
"Type": "String",
"Value": "tier=production"
},
"Type": "AWS::SSM::Parameter"
},

two-stack リリースをビルドすると、この点はより明確になります。各境界がそれぞれ独自のものを持ち、その境界自身の解決済み設定を保持します。そのビルドが書き出す 2 つのテンプレートそれぞれにあるものの Properties は次のとおりです。

"Properties": {
"Description": "Settings shared by every component in the data boundary",
"Name": "/data/shared-config",
"Type": "String",
"Value": "tier=production-data"
},
"Properties": {
"Description": "Settings shared by every component in the app boundary",
"Name": "/app/shared-config",
"Type": "String",
"Value": "tier=production-app"
},

これが Release でアタッチされるのは、保持する内容が Aggregate の宣言ではなく、オペレーター自身の構成だからです。境界アタッチメントは infra: を設定し、values: は決して設定しません。開発者の値が記述される場所は引き続き Aggregate です。

同じ意図を 2 つのスタックに分割する

Terminal window
aggrega pull --release release-two-stacks.yaml
aggrega build --release release-two-stacks.yaml

aggregate.yaml は何も変わりません。アプリケーションは引き続きデータベースを使用することを宣言します。2 つを別々にプロビジョニングすることはオペレーターが Release で決定し、その結果として両者の間の参照がスタックの境界をまたぎます。

1 スタックのビルドでは、アプリケーションはエンドポイントを単一のテンプレート内の参照として受け取ります。

"Properties": {
"Name": "/reporting/db-host",
"Tier": "Standard",
"Type": "String",
"Value": {
"Fn::GetAtt": [
"PaymentsDb",
"Endpoint.Address"
]
}
},

2 スタックのビルドでは、プロデューサー側のスタックがその値をエクスポートとして公開します。

"paymentsXzhdbXXhost": {
"Value": {
"Fn::GetAtt": [
"PaymentsDb",
"Endpoint.Address"
]
},
"Export": {
"Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"
}
},

そして、コンシューマー側のスタックがその同じ名前でそれを読み戻します。

"Properties": {
"Name": "/reporting/db-host",
"Tier": "Standard",
"Type": "String",
"Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"}
},

Export を持つのは host だけです。エッジが実際に消費するエントリがそれだからです。データベースが公開するほかのエントリは通常の出力として現れます。コンポーネントスコープのアラームはホストに従ってプロデューサー側のスタックに入り、各境界はそれぞれ自身の境界全体のアタッチメントを保持します。

どちらの組み込み関数もビルド時には評価されません。エンドポイントはスタックがデプロイされるまで存在しないため、コンパイラは参照をそのまま渡し、CloudFormation がそれを解決します。アプリケーションがアドレスを一切指定しないのはこのためです。

エクスポート名の構築方法と、コンシューマーがアカウントをまたぐ直接の読み取りではなく Fn::ImportValue を通じて読み取るのはどのような場合かについては、スタック間の接続を参照してください。

停止するビルド

Terminal window
aggrega pull --release release-negative-name-collision.yaml
aggrega build --release release-negative-name-collision.yaml

aggregate-name-collision.yaml は、1 つのコンポーネントにアラームを 2 つのアタッチメント名で2 回アタッチします。各アタッチメントのリソース名はそれぞれのアタッチメント名を組み込むため、2 つのアラームは別個の 2 つのリソースとなり、そこでは衝突しません。衝突するのは出力です。どちらも alarm-id を公開し、出力はホストコンポーネントとエントリに基づいて命名され、ホストは両方とも同じコンポーネントだからです。

[… omitted: the pull's lines, which report the same collision while writing the lockfile]
[TRANSLATION_ERROR E0038]
dispatch groups whose contributors derive one name more than once in one key space
caused by (2):
[TRANSLATION_ERROR] release-negative-name-collision.yaml
derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation")
---
[TRANSLATION_ERROR] release-negative-name-collision.yaml
derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")

ここから読み取れることが 4 つあり、いずれも意図的なものです。

  • 両端が名指しされます。 各エントリは、コンポーネントとそれが持っていたアタッチメント名を示すため、どちらも自分で書いたファイル内で検索できます。衝突において一方の寄与者の名前が意図されたものだと判断できる要素はないため、最初のものだけでなく両方が報告されます。
  • キー空間が名指しされます。 output-logical-ids は、スタックの 2 つの名前空間のうちどちらに達したかを示し、さらに、この停止にリソース名前空間が含まれていないことから、リソース名には問題がなかったことも示します。
  • 何も出力されません。 2 つのアラームの一方が出力を持たないまま黙って書き出されたスタックを作るのではなく、ビルドは停止します。
  • リソースに別々の名前を付けても、これは解決しません。 出力名はホストコンポーネントとエントリから組み立てられるため、異なる必要があるのはエントリです。つまり、アタッチメントを 2 つではなく 1 つにするか、公開エントリ名がそのアタッチメント固有のものとして読める Feature を使うかのいずれかです。

同一の入力、同一の出力

変更のない入力から 2 回ビルドすると、バイト単位で同一のテンプレートが生成されます。 コンパイラはライブデータを一切解決しません。AWS を呼び出すことも、アカウント 識別子を検索することも、CloudFormation を実行することもありません。そのため、再ビルドでバイトを変化させうるものが新たに見つかることはありません。これが差分ベースのレビューが前提とする性質です。

dist/ と *.lock ファイルは生成物であり、コミットされません。これらは コミットされているファイルから再生成されます。