こんにちは。ディベロップメントサービス3課の千本松です。
以前の記事でCDK Migrateを使用してAWS CloudFormation（以下、CloudFormation）からAWS CDK（以下、CDK）への基本的な移行を行いました。
今回は、生成されたCDKコードをより実用的にするため、メタデータを含まず、リソース差分のないテンプレートの生成に焦点を当てます。
メタデータを除去して既存のCloudFormationスタックとの差分を無くすことで、既存リソースが変更・置換される心配なく移行作業を進めることができます！
以前と同じAmazon EC2（以下、EC2）スタックを題材に、実際の検証結果を交えながら解説します。
以前の記事はこちら：AWS CloudFormationスタックをAWS CDKで管理！CDK Migrateを使ってみた - サーバーワークスエンジニアブログ
CDK Migrateとは
CDK Migrateは、CloudFormationのスタックやテンプレートをCDKコードに変換するための機能であり、CDK内のコマンドとして提供されています
ただし、現状実験的な機能として提供されており、将来的に破壊的な変更が加わる可能性がある点に注意が必要です。（2025年7月時点）
The cdk migrate command is experimental and may have breaking changes in the future.
主な検証のポイント
- CDK Migrateで生成されたコードをデプロイする際に、メタデータを除去して、既存スタックとの差分を無くす手順
検証環境について
今回の検証で使用した環境は以下の通りです。
- Bash（コマンド実行）
- AWS CDK v2.1020.2
- Python 3.13.5
- リージョン: ap-northeast-1
CDK Migrateで生成されたコードの課題
CDK Migrateで変換したコードをそのまま使った場合、変更セットがどうなるか確認します。
※ 変換前のCloudFormationテンプレート全文は、前回の記事で紹介しています。
リソースレベルの変更
EC2インスタンスのプロパティレベルの変更
この変更セットでは以下の変更が検出されています。
特に、aws:cdk:pathは全てのリソースに追加されるため、意図しない差分が含まれていないかの確認が大変です。
AWS::CDK::Metadataリソースが追加されている- 各リソースに
aws:cdk:pathメタデータが付与されている
メタデータを含まないテンプレートの生成
ここからが本題です。
CDKの設定を変更して、メタデータを含まないテンプレートが生成されるようにします。
メタデータ除去の設定
cdk.jsonに以下の項目を追加します。
{ "versionReporting": false, "pathMetadata": false }
各設定の効果：
versionReporting: false→AWS::CDK::Metadataリソースを除去pathMetadata: false→aws:cdk:pathメタデータを除去
※ デプロイコマンドに各オプションを指定することも可能です
参考：AWS CDK CLI リファレンス - AWS クラウド開発キット (AWS CDK) v2
デプロイ済みスタックとの変更差分の確認
変更セットを生成して差分を見てみます。
cdk deploy --region ap-northeast-1 --no-execute
変更セットの内容
変更セットを確認すると、ちゃんと差分がなくなっていました！
メタデータ除去による影響と対応
各メタデータを除去することで、CDKの機能を最大限に活用できなくなる可能性があります。
メタデータを含めたい場合は、差分無しでの移行をしてから再度メタデータを有効にしてデプロイすることで、意図しない変更が含まれるリスクが下がり、差分確認の手間を軽減できます。
AWS::CDK::Metadataリソースの除去による影響
AWS::CDK::Metadataリソースは、AWSのCDKチームがCDKの使用状況を把握するために利用されるようです。
CDKの利用上は大きな影響はないと思われますが、各プロジェクトの利用方針に応じて対応を検討してください。
・顧客との通信 — セキュリティまたは信頼性の既知の問題があるコンストラクトを使用してスタックを特定し、顧客に影響を与えるトピックに関する通信を送信します。
・CDK 開発の通知 – CDK の使用に関するインサイトを取得して、CDK 開発により良い情報を提供します。
・CDK の問題を調査する – バグが報告されると、使用状況データはトラブルシューティング時に CDK チームに貴重なインサイトを提供します。
参考：AWS CDK 使用状況データレポートを設定する - AWS クラウド開発キット (AWS CDK) v2
aws:cdk:pathメタデータの除去による影響
残念ながら、こちらのメタデータの機能を直接的に解説しているドキュメントは見つかりませんでした。
CDKコマンドに無効化するためのオプションが存在することから、無効化によって致命的な問題が発生する可能性は少ないと思いますが、各プロジェクトの利用方針に応じて対応を検討してください。
参考：Identifiers and the AWS CDK - AWS Cloud Development Kit (AWS CDK) v2
まとめ
今回は、CDK Migrateで生成されたコードからメタデータを除去し、既存のCloudFormationスタックとの差分を無くす方法について解説しました。
差分を取り除くことでCDK移行時の変更内容が明確になり、意図しない変更を見逃すリスクを低減できます。
また、既存リソースの変更・置換される心配なく移行作業を進めることができます。
最後までお読みいただきありがとうございました！
本ブログが誰かの参考になれば幸いです。
