テーマ別の解説テーマ:AWS CDK:コードと合成物
AWS CDKのsynthとは?ConstructとCloudFormationの関係を図解
AWS CDKはプログラムで構成を表し、synthでCloudFormationテンプレートなどのデプロイ用のファイル一式を作ります。 合成できたことと、AWSに反映できたことは別です。短いコードを、包含関係・参照・変更の確認という三つの観点で読みます。
App・Stack・Constructの関係を読み、合成物の確認とAWSへの適用を分けて説明する。
CloudFormationのResources・論理ID・Refを知っていると読みやすい教材です。TypeScriptの細かな文法は知らなくても構いません。ここではコードを読むだけで、CDKやAWSを実行しません。
コードから合成物へ、その後にデプロイする
| 段階 | 扱うもの | 確認すること |
|---|---|---|
| 記述 | プログラムで宣言した構成 | 作る資源、参照、条件、既定値。 |
| 合成(synth) | CloudFormationテンプレートやassets等のcloud assembly | 生成された資源とプロパティ、配布に必要な成果物。 |
| 適用と検証 | 対象のAWS環境と実際の機能 | 変更の影響と適用結果、その後の通信やアプリ。 |
cloud assemblyはテンプレートだけとは限りません。 アプリが必要とするファイルやイメージのassetsなども対象になります。コードレビューでは、プログラムの読みやすさに加えて、生成される構成を確認します。
App・Stack・Constructは、構成を組み立てる単位
- App → ReportStack含む
- ReportStack → ReportNetwork含む
- ReportStack → ReportGroup含む
- App
- 構成を組み立てるアプリ
- ReportStack
- この例のStack
- ReportNetwork
- VPCを宣言するL1
- ReportGroup
- SGを宣言するL1
Constructは構成を表す部品、StackはCloudFormationスタックとして扱うまとまり、Appはそれらを組み立てるアプリです。 図のSGからVPCへ通信する、という意味ではありません。資源同士の参照は、次のコードのプロパティで読みます。
固定例:VPCの参照をセキュリティグループへ渡す
import { App, Stack, aws_ec2 as ec2 } from 'aws-cdk-lib';
const app = new App();
const stack = new Stack(app, 'ReportStack');
const network = new ec2.CfnVPC(stack, 'ReportNetwork', {
cidrBlock: '10.20.0.0/16'
});
new ec2.CfnSecurityGroup(stack, 'ReportGroup', {
groupDescription: 'Illustrative group',
vpcId: network.ref
});
app.synth();| コード | 読み方 |
|---|---|
| new Stack(app, 'ReportStack') | appの内側にStackを置く。 |
| new ec2.CfnVPC(stack, 'ReportNetwork', ...) | Stack内にVPCを表すL1 Constructを置く。 |
| vpcId: network.ref | 合成後にCloudFormationが解決するVPCのRefを渡す。 |
| app.synth() | アプリの構成から合成物を生成する。AWSでの適用成功を示す行ではない。 |
部品の抽象度と、資源の識別子を分ける
| 種類 | 何を表すか | レビューの観点 |
|---|---|---|
| L1 | CloudFormation資源に直接対応する低水準の部品。Cfnから始まる型が目印。 | 必要なプロパティを明示する。 |
| L2 | 使いやすいAPIや補助機能を持つ部品。 | 既定値・権限など生成される設定も読む。 |
| L3・パターン | 複数の部品を組み合わせた構成。 | 省略した記述の裏で、何が作られるか確認する。 |
| 種類 | 役割 |
|---|---|
| Construct ID | 同じscope内で部品を識別するコード上のID。 |
| CloudFormation論理ID | 合成テンプレート内で資源を追跡するID。Constructのpathが生成に関わる。 |
| 実リソースの識別子 | 作成された資源のIDや名前。コード上のIDと常に同じとは限らない。 |
Constructの移動やID変更は、論理IDを変え、資源の作り直しにつながることがあります。コードの整理を、必ず資源に影響しない変更と扱わないでください。生成物と差分で同一性や置換の有無を確認します。論理IDは名前だけから決めつけず、実際の生成物で照合します。
synthの成功だけで、安全性や適用成功を決めない
synthではアプリのコードが実行されます。環境値の取得(context lookup)やassetsの作成条件によっては、AWSへの問い合わせや別の処理が関係します。synthなら無条件にオフラインで無害、と考えないことが大切です。
- アプリと依存する部品を読み、実行時の処理とlookupの条件を確認する。
- 生成されたテンプレートとassetsを確認し、変更・権限・置換や削除の影響を読む。
- 対象の環境・権限・承認内容をそろえて適用し、結果と実際の機能を確認する。
構成の読み方を確かめる
選択すると、正誤と理由が表示されます。
確認して、自分の言葉で説明する
- 包含図でApp・Stack・Constructを分ける。
- 固定コードのscopeとRefを読む。
- 設問と復習で、合成後の確認事項を説明する。
理解を確かめる: CDKのレビューで、コード以外に何を確認する?
生成されるテンプレートとassets、資源の参照と論理ID、権限や置換・削除の差分、対象環境と適用後の機能を確認する。
読みやすいコード、生成物、適用結果、実際の機能は別の確認対象だから。
出典と確認した条件
説明に用いた公式資料を、確認した内容・条件と本文の参照箇所に分けてまとめています。専門家による監修・実際のAWSとの比較検証は行っていません。
確認した内容・条件cloud assemblyのテンプレート・assets、synthesizerと配布条件を確認。合成成功をデプロイ成功と扱わない。
確認した内容・条件AppとStack、合成時のアプリ実行、合成物と適用の段階を確認。実行検証ではない。
参照した本文コードから合成物へ、その後にデプロイする App・Stack・Constructは、構成を組み立てる単位 固定例:VPCの参照をセキュリティグループへ渡す synthの成功だけで、安全性や適用成功を決めない 構成の読み方を確かめる
確認した内容・条件Constructの包含とL1/L2/L3、抽象化と生成される設定を確認。包含図を通信経路としない。
参照した本文App・Stack・Constructは、構成を組み立てる単位 部品の抽象度と、資源の識別子を分ける 構成の読み方を確かめる
確認した内容・条件CfnVPCのscope/id/cidrBlock/refを固定TypeScript読解に使用。compile・synth・AWS作成は未実施。
確認した内容・条件CfnSecurityGroupの初期化とgroupDescription。固定例は本番向け通信設定の完成ではない。
確認した内容・条件必須のgroupDescriptionと、vpcIdが指定するVPCの型・意味を確認。
参照した本文固定例:VPCの参照をセキュリティグループへ渡す
確認した内容・条件scope内ID・path・論理ID・物理識別の違いとrefactorの置換リスク。未実行のハッシュは示さない。
参照した本文部品の抽象度と、資源の識別子を分ける synthの成功だけで、安全性や適用成功を決めない 構成の読み方を確かめる
確認した内容・条件環境から取得するcontextとキャッシュの条件。すべてのsynthが無条件にオフラインとはしない。