AWS CDK 開発を成功に導くトラブルシューティングガイド

Ops-JAWS Meetup35 IaC CDK支部コラボレーション企画で発表した内容です。
今回のセッションでは「リソースを CDK 外で変更してしまった」場合に焦点を当てました。

上記も含めて、AWS CDK における遭遇しがちなエラーや躓きがちなポイントをまとめて AWS Black Belt Online Seminar にて公開する予定です！その際は是非ご覧ください！

Transcript

1. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. AWS Cloud Development kit (CDK) 中島 亮太 クラウドサポート エンジニア 2025/07 AWS CDK 開発を成功に導くトラブルシューティングガイド
2. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 中島 亮太 アマゾン ウェブ サービス ジャパン合同会社 クラウドサポート エンジニア 好きな AWS サービス 2 AWS CDK Amazon ECS Amazon Bedrock
3. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. • リソースを CDK 外で変更してしまった (本セッションで扱う内容) • スタック削除時に残ったリソースの探し⽅ • CDKtoolkit スタックを削除してしまった • クロススタック参照のデッドロック • クロスリージョン参照のデッドロック • CDK が作成する AWS Lambda 関数のランタイムバージョンの更新 • and more.. 3 アジェンダ 上記と併せて AWS Black Belt Online Seminar にて公開予定︕ AWS CDK で遭遇しがちなエラーとその対処法をご紹介
4. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. リソースを CDK 外で変更してしまった 4
5. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. • スタック配下のリソースを CDK (or AWS CloudFormation) 外で更新してしまうと、テンプ レートとスタック配下のリソースが⼀致しない「ドリフト」状態となる • ドリフト状態のスタック更新/削除は想定された操作ではなく、次回のスタック更新や削 除時にエラーが発⽣する可能性があるため、まずはドリフトを先に解消する必要がある リソースを CDK 外で変更してしまった 5 CloudFormation ベストプラクティス https://docs.aws.amazon.com/ja_jp/AWSCloudFormation/latest/UserGuide/best-practices.html#donttouch スタックのリソースを CloudFormation 以外の⽅法で変更しないでください。変更する とスタックのテンプレートとスタックリソースの現在の状態の間で不⼀致が起こり、ス タックの更新または削除でエラーが発⽣する場合があります。これをドリフトと呼びます。 緊急対応に伴い⼿動で設定を 変更してしまった..
6. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. • リソースの更新時に中断 or 置換を「伴わない」プロパティを変更していた場合 リソースを CDK 外で変更してしまった場合の対処法 6 1. 実際のリソースの状況に合わせてプロパティを変更してスタックを更新 • リソースの更新時に中断 or 置換を「伴う」プロパティを変更していた場合 1. スタックの管理下からリソースを外す 2. 実際のリソースの状況に合わせてプロパティを変更しインポート操作を実施 TypeScript const instance = new ec2.Instance(this, 'Instance', { vpc, instanceType: ec2.InstanceType.of( ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.SMALL // t3.small ), machineImage: ec2.MachineImage.genericLinux({ 'ap-northeast-1': 'ami-0bb2c57f7cfafb1cb’ }) }); cdk.Tags.of(instance).add(‘Test’, ‘1’); // Test:1 タグを付与 • ここでは Amazon EC2 インスタンスを題材としてトラブルシューティングを紹介 ⼿順が複雑となるため本番環境に適⽤する 前に検証環境でテストすることを推奨
7. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 中断 or 置換を「伴わない」プロパティを変更していた場合 7 例) EC2 コンソールからタグを「Test: 2」へと変更した場合 2. cdk diff を実⾏して変更内容を確認 Console [~] AWS::EC2::Instance Instance InstanceC1063A87 └─ [~] Tags └─ @@ -5,6 +5,6 @@ [ ] { [ ] "Key": "Test", [-] "Value": "1" [+] "Value": "2" [ ] } 1. 実際のリソースの状況に合わせてプロパティを変更 TypeScript cdk.Tags.of(instance).add('Test', ‘2'); 3. 対象のプロパティが Update requires: No interruption か確認 Tags .. Update requires: No interruption No interruption リソースの操作を中断したり、リソースの物理 ID を変更 することなくリソースを更新可能 4. スタックを更新 Console $ cdk deploy *1 https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-instance.html#cfn-ec2-instance-tags 1. リソースタイプ (AWS::EC2::Instance) を検索 2. 対象リソースのリファレンスページにてプロパティ (Tags) を確認
8. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 中断 or 置換を「伴う」プロパティを変更していた場合 8 1. リソースの状況に合わせた上で cdk diff を実⾏すると may be replaced と表⽰される Console [~] AWS::EC2::Instance Instance InstanceC1063A87 may be replaced └─ [~] InstanceType (may cause replacement) ├─ [-] t3.small └─ [+] t3.medium InstanceType When you change your EBS-backed instance type, instance restart or replacement behavior depends on the instance type compatibility between the old and new types. .. Update requires: Some interruptions Some interruptions リソース更新時に中断を伴う 2. InstanceType プロパティはリソース更新時に置換 or 再起動を伴う *1 *1 https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-instance.html#cfn-ec2-instance-instancetype 例) EC2 コンソールからインスタンスタイプを t3.medium に変更した場合
9. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 中断 or 置換を「伴う」プロパティを変更していた場合 9 スタックの管理下からリソースを外す 対象のリソースがインポート可能か確認 実際のリソースの状況に合わせてプロパティ を変更しインポート操作を実施 Retain ポリシーを付与して更新 リソースをコメントアウトして更新 stack stack リソースをインポート AWS Management Console Document
10. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 3. CloudFormation コンソールの「リソース」タブから 対象リソースの物理 ID とリソースタイプを確認 (物理 ID は cdk import で使⽤するため控えておく) 4. 各リソースタイプがインポートに対応しているか ドキュメントから確認 L2、L3 コンストラクトを使⽤しており、 複数の CloudFormation リソースが配下に 存在する場合はまとめてインポートする https://docs.aws.amazon.com/ja_jp/AWSCloudFormation/latest/U serGuide/resource-import-supported-resources.html リソースタイプのサポート 10 対象のリソースがインポート可能か確認 中断 or 置換を「伴う」プロパティを変更していた場合
11. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 中断 or 置換を「伴う」プロパティを変更していた場合 11 TypeScript const instance = new ec2.Instance(this, 'Instance', { vpc, instanceType: ec2.InstanceType.of( ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.SMALL // 元の設定に戻す ), machineImage: ec2.MachineImage.genericLinux({ 'ap-northeast-1': 'ami-0bb2c57f7cfafb1cb’ }) }); cdk.RemovalPolicies.of(instance).retain(); *1 https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/core/README.md#removalpolicies 5. プロパティを元の設定に戻し対象のリソースに RemovalPolicy.Retain を付与 Console $ cdk synth // テンプレート側で DeletionPolicy: Retain が付与されているか確認 $ cdk deploy スタックの管理下からリソースを外す 6. cdk synth を実⾏ 7. 出⼒されたテンプレートの対象リソースに DeletionPolicy: Retain が付与されていることを確認 8. cdk deploy によりスタックを更新 RemovalPolices を⽤いて instance コンストラクト配下 の全てのリソースに Retain ポリシーを付与 *1
12. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 中断 or 置換を「伴う」プロパティを変更していた場合 12 9. リソースをコメントアウトしてスタックを更新 Console $ cdk deploy スタックからリソースは削除されるが instance コンストラクト配下のリソースは保持される スタックの管理下からリソースを外す TypeScript // const instance = new ec2.Instance(this, 'Instance', { // vpc, // instanceType: ec2.InstanceType.of( // ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.SMALL // ), // machineImage: ec2.MachineImage.genericLinux({ // 'ap-northeast-1': 'ami-0bb2c57f7cfafb1cb' // }) // }); // cdk.RemovalPolicies.of(instance).retain();
13. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. 中断 or 置換を「伴う」プロパティを変更していた場合 13 10. 実際のリソース状況に合うように CDK 側を変更 TypeScript const instance = new ec2.Instance(this, 'Instance', { vpc, instanceType: ec2.InstanceType.of( ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.MEDIUM // t3.medium ), machineImage: ec2.MachineImage.genericLinux({ 'ap-northeast-1': 'ami-0bb2c57f7cfafb1cb’ }) }); 11. cdk import を実⾏ (各リソースの物理 ID を指定) Console $ cdk import .. (AWS::EC2::SecurityGroup): enter Id (empty to skip) sg-0dcfc4587cb752e97 (AWS::IAM::Role): enter RoleName (empty to skip) ManualChangeStack-InstanceInstanceRoleE9785DE5-wIVghBfcqwjA (AWS::IAM::InstanceProfile): enter InstanceProfileName (empty to skip) ManualChangeStack-InstanceInstanceProfileAB5AEF02-klHNcG1roUtp (AWS::EC2::Instance): enter InstanceId (empty to skip) i-0647c808e674aa330 実際のリソースの状況に合わせてプロパティを 変更しインポート操作を実施 cdk import https://docs.aws.amazon.com/cdk/v2/guide/ref-cli-cmd-import.html
14. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Tips: cdk drift コマンド 14 • aws-cdk v2.1017.0 に追加された新機能 • CloudFormation のドリフト検出 (テンプレートに設定されたプロパティと実際のリソースの値と の整合性を確認する機能) を cdk コマンドから実⾏可能 Console $ cdk drift ✨ Synthesis time: 5.29s Stack ManualChangeStack Modified Resources [~] AWS::EC2::Instance InstanceC1063A87 └─ [~] /InstanceType ├─ [-] t3.small └─ [+] t3.medium cdk drift https://docs.aws.amazon.com/cdk/v2/guide/ref-cli-cmd-drift.html
15. © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. Thank you! © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.