初心者がおさえておきたいAWS CDKのベストプラクティス 2024

「AWS CDKに興味を持ったけれど、なかなかコードを書き始められない」と悩んでいませんか？CDKは簡単に始めることができますが、メンテナンスしやすく、壊れにくいコードを書くためには覚えておきたいプラクティスがあります。しかし、すべてのエンジニアがインフラ構築やプログラミングに精通しているわけではなく、CDKのスタート地点は人それぞれです。このセッションでは、AWS IaCのエキスパートとして多くのお客様を支援した経験と個人的な思いを織り交ぜて、CDKのコードを書くために最初におさえておきたいベストプラクティスをやさしく解説します。

AWS CDK Conference Japan 2024 の資料です

Transcript

1. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 初⼼者がおさえておきたい AWS CDK のベストプラクティス 2024 A W S C D K C O N F E R E N C E 2 0 2 4 ⾼野 賢司 シニア ソリューション アーキテクト アマゾン ウェブ サービス ジャパン合同会社 2024/7/6
2. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk ⾼野 賢司 こ う の け ん じ AWS CDK / IaC の アップデート情報を X でつぶやいています #cdk_releases @konokenj ※ v2.29.0 (2022年6⽉) から • Infrastructure as Code (IaC) の ⽇本における技術⽀援をリード • Baseline Environment on AWS (BLEA) の開発者 https://github.com/aws-samples/baseline-environment-on-aws シニア ソリューション アーキテクト @名古屋 アマゾン ウェブ サービス ジャパン合同会社
3. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk AWS CDK を使うエンジニアの得意領域は⼈それぞれ 3 Lv 1 Lv 2 Lv 3 インフラエンジニア アプリエンジニア 本セッションで紹介するプラクティスは唯⼀の正解ではありません AWS CDK の学び始めにおける余計な認知負荷を下げるための 2024 年時点でのコレクションです 使い始めに知っておきたい 基礎知識をカバーします
4. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk 4 ベストプラクティスは コミュニティから⽣まれます JAWS-UG CDK ⽀部の皆様、 CDK のコントリビューターの皆様、 いつもありがとうございます︕
5. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk 1. ドキュメントを読む 2. しくみを理解する 3. Tenets に共感する 4. 困ったときの相談先を知る 5. Git でバージョン管理する 6. Git リポジトリにすべてを保存する 7. Git リポジトリとチームの境界をあわせる 8. IDE の機能を活⽤する 9. ⽣成 AI を活⽤する 10. はじめから標準化しない 11. リソースの置き換えに注意する 12. ハイレベルなコンストラクトを使う 13. grant / metric / connections を使う 14. 必要になるまでスタックは分けない 15. コンストラクトで構造化する 16. ベタ書きからはじめる 17. パラメータは App レベルから注⼊する 18. スナップショットテストを書く 19. リソース名でなく Construct ID にこだわる 20. コードベースと環境の⼀貫性を保つ 初⼼者がおさえておきたい AWS CDK のベストプラクティス 20 選 5 ソフトウェア開発の基本 AWS CDK の基本
6. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk ソフトウェア開発の 基本的なプラクティス 6
7. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk ドキュメントを読む 7 1 AWS CDK Developer Guide https://docs.aws.amazon.com/cdk/ v2/guide/home.html AWS CDK のコンセプトや 実践的なベストプラクティスなど 開発に役⽴つ情報を記載 API Reference https://docs.aws.amazon.com/cdk/api/ v2/docs/aws-construct-library.html API の仕様はこちらで確認。 各モジュールの Overview を 読もう︕ GitHub repository https://github.com/aws/aws-cdk AWS CDK の開発リポジトリ 最新の開発状況や Design Doc などを確認できる
8. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk しくみを理解する 8 2 プログラミング⾔語で インフラ構成を定義 開発者 クラウドリソース ⽬的の状態に収束 API 呼び出し AWS CloudFormation テンプレートに定義された 状態になるようリソースを操作 テンプレートを実⾏ AWS CDK Toolkit (CLI) CloudFormation テンプレートを合成 アプリやデータを アセットとしてデプロイ $ cdk deploy © 2024, Amazon Web Services, Inc. or its affiliates. © 2023, Amazon Web Services, Inc. or its affiliates. AWS Black Belt Online Seminar AWS Cloud Development Kit (CDK) 基本的なコンポーネントと機能 ⾼野 賢司 Solutions Architect 2023/08 Basic #2 AWS Black Belt Online Seminar で詳しく解説しています
9. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk Tenets に共感する • Tenets = 意思決定のための組織や製品の信条。何に価値を置くかを明らかにする • フレームワークの選定や、上⼿に使い続けるのに Tenets の理解が役⽴つ 9 3 • Werner Vogels on the AWS Cloud Development Kit https://www.youtube.com/watch?v=AYYTrDaEwLs • The tenets of the AWS CDK https://github.com/aws/aws-cdk/blob/main/ docs/DESIGN_GUIDELINES.md#preface • Working backwards: The story behind the AWS Cloud Development Kit https://aws.amazon.com/jp/blogs/opensource/ working-backwards-the-story-behind-the-aws-cloud-development-kit/ • Meet developers where they are • Full coverage • Designerd for the CDK • Open • Designed for jsii
10. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk 困ったときの相談先を知る 10 4 AWS Support https://aws.amazon.com/jp/premium support/ AWS の技術サポートに 問い合わせ可能 デベロッパーサポート以上が必要 AWS re:Post https://repost.aws/ AWS 公式の Q&A サービス コミュニティや専⾨家への 質問や記事の公開が可能 cdk.dev https://cdk.dev/ コミュニティの ブログ記事などを紹介 Slack channel で質問できる 『技術的なお問い合わせに関するガイドライン』は必読︕ https://aws.amazon.com/jp/premiumsupport/tech-support-guidelines/
11. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk Git でバージョン管理する Git はコミュニケーションツール • バージョン管理機能だけでなく チームのインタラクション⽅法として重要 Git はシステム間連携のインターフェイス • あらゆる開発ツールや⾃動化は Git を統合の起点にしている 11 5 AWS Well-Architected Framework - DevOps Guidance https://docs.aws.amazon.com/wellarchitected/latest/devops-guidance/dl.scm.1-use-a-version-control-system-with-appropriate-access-management.html 公式
12. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk Git リポジトリにすべてを保存する プライベートな Git リポジトリにすべてを保存 • AWS アカウント ID やリージョンなども含め すべてをコードとしてコミットして 実⾏時のパラメータや環境への依存を排除 依存関係をロックする • package-lock.json, poetry.lock 等をコミット コンテキスト情報の⼀貫性を保つ • cdk.context.json をコミット 12 6 AWS CDK Best Practices https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html Git リポジトリを⾒れば アプリ全体の 状態がわかるようにする 公式
13. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk Git リポジトリとチームの境界を合わせる 「1 Git リポジトリ = 1 CDK App」を原則にする • CDK App はアプリ全体を定義する • CDK App が複数同居するとデプロイの爆発半径が拡⼤ コンウェイの法則を念頭に置く • アーキテクチャは組織構造やチーム間の 実際のコミュニケーションを反映したものになる • Git リポジトリの分け⽅は コミュニケーションパスに影響を与える 13 7 AWS CDK Best Practices https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html 公式
14. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk IDE の機能を活⽤する 14 8 コード補完 / Linter / Formatter スニペット VSCode + TypeScript なら特に設定不要。 Python の場合は Python 拡張の導⼊と設定が必要: "python.analysis.typeCheckingMode": "standard" Linter / Formatter の設定には BLEA のサンプルや Projen を活⽤ 定型⽂はスニペットに登録。 CDK App, Stack, Construct の雛形を作ってみよう
15. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk ⽣成 AI を活⽤する 15 9 Amazon Q Developer • AWS CloudFormation, AWS CDK (TypeScript, Python), HashiCorp Terraform (HCL) をサポート • IaC コードのセキュリティスキャン • ⾃動スキャンは要 Pro Tier • スキャン機能は ⽣成 AI には⾮依存 https://aws.amazon.com/about-aws/whats-new/2024/04/amazon- q-developer-generally-available/ Amazon CodeWhisperer にて AI を活⽤した新しいコード修正、 IaC サポート、および Visual Studio との統合提供を開始 https://aws.amazon.com/jp/blogs/news/amazon-codewhisperer- offers-new-ai-powered-code-remediation-iac-support-and- integration-with-visual-studio/
16. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk はじめから標準化しない Platform as a Product • エンジニアを顧客として プラットフォームの価値を測定し、説明する • エンジニアの認知負荷を軽減するために実験を繰り返す Thinnest Viable Platform • 経験を積み、軽減したい認知負荷を特定してから作る • 開発者体験から逆算して、最⼩限の標準や規約にする • ⾃動化を前提にする • 「うちの組織だけは特別」ではない。先⼈に学ぼう 16 10 フィードバック ループが必要
17. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk AWS CDK の 基本的なプラクティス 18
18. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk リソースの置き換えに注意する cdk diff や変更セットで変更を確認しよう 論理 ID の変更に注意 • Construct ID を変更したり Construct を別の階層に移動したりすると 論理 ID が変わり必ず置き換えになる SSM Parameter など、CDK の外部で変更される値に注意 • EC2 Instance の AMI ID に SSM Parameter を使⽤する場合、キャッシュ指定の有無を確認 • ec2.MachineImage.latestAmazonLinux2023 → cachedInContext: true の指定が必要 • ec2.AmazonLinux2023ImageSsmParameter → デフォルトでキャッシュが有効 • https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2-readme.html 19 11 Construct ID = コンストラクタの第2引数に指定する⽂字列
19. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk ハイレベルなコンストラクトを使う 抽象化はソフトウェアの正常な発展の形（こわくない） • エスケープハッチで L1 コンストラクトが取得可能 • スナップショットテストで意図しない変更を検知 すべての設定値を明⽰的に指定するとレビューが困難に • コード量が増加するとメンテナンス性が低下する • デフォルト値との差分や意図がわからなくなる 20 12 抽象化は AWS CDK の⽬的のひとつ https://www.youtube.com/watch?v=AYYTrDaEwLs
20. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk grant / metric / connections を使う 21 13 © 2024, Amazon Web Services, Inc. or its affiliates. grant | 権限設定を抽象化 • Amazon S3 Bucket や Amazon DynamoDB Table などアクセス可能なリソースの L2 Construct には grant で始まるメソッドが実装されている • 複雑な IAM ポリシーを設計することなく 簡単に最⼩権限に設定できる • IGrantable を実装しているリソースを指定可能 • IAM User / Role / Group / Policy など • Lambda Function, EC2 Instance などの⼀部のリソース 11 const bucket = new Bucket(this, 'Bucket'); const f = new NodejsFunction(this, 'Func', { entry: 'lambda/list-object.ts', handler: 'handler', runtime: Runtime.NODEJS_18_X, environment: { BUCKET_NAME: bucket.bucketName, }, }); bucket.grantRead(f); TypeScript https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk- lib.aws_iam.IGrantable.html AWS CDK Best Practices https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html 公式 複雑な設定を 簡単に⾏えるのが CDK のメリット AWS Black Belt Online Seminar を参照
21. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk 必要になるまでスタックは分けない 22 14 2023/05/20 AWS CDK CONFERENCE JAPAN © 2023, Amazon Web Services, Inc. or its affiliates. Twitter: #jawsug_cdk Q. ελοΫ͸Ͳ͏෼͚Δͷ͕ྑ͍ʁ • جຊϧʔϧ: ඞཁ͕ͳ͍ͳΒ෼͚ͳ͍ • ελοΫΛ෼͚Δͱେ఍ͷ৔߹ελοΫؒͷґଘؔ܎͕ੜ͡Δ (ελοΫؒࢀরͳͲ, ޙड़) • ελοΫؒࢀর͸։ൃŋӡ༻্ଟ͘ͷ໘౗ΛҾ͖ى͜͢͜ͱ͕ଟ͍ (ޙड़) • ελοΫΛ෼͚Δඞཁ͕͋Δͱ͖ 1. Ϧιʔε਺500Λ௒͑Δ࣌ (CloudFormationͷϋʔυϦϛοτ) 2. ϚϧνΞΧ΢ϯτɺϚϧνϦʔδϣϯ (ಛఆϦʔδϣϯͰ͔͠࡞Εͳ͍Ϧιʔε΋͋Γ) 3. ϦιʔεΛσϓϩΠ͢ΔؒʹCloudFormation֎ͷૢ࡞͕ඞཁͳͱ͖ • ྫ: όοΫΤϯυͷσϓϩΠ → ϑϩϯτΤϯυͷ؀ڥม਺ (API URLͳͲ) ΛຒΊࠐΜͰϏϧυ → ϑϩϯτΤϯυͷσϓϩΠ • ΧελϜϦιʔεͰؤுΕ͹ղফ͢Δ৔߹΋ଟ͍͕ɺෳࡶʹͳΔͷͰߟ͑΋ͷ • ඞཁ͕͋Δ͔Ͳ͏͔Θ͔Βͳ͍ͱ͖: ·ͣ͸෼͚Δ͜ͱͰ۩ମతͳϝϦοτ͕͋Δ͔ߟ͑Δ 6 • CloudFormation の 考え⽅を踏襲しない • マルチスタックが 適する場合もあるが、 メリットが明確に 説明できるまでは避ける ← AWS CDKのあるあるお悩みに答えたい https://speakerdeck.com/tmokmss/answer ing-cdk-faqs?slide=6 AWS CDK Best Practices https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html 公式
22. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk コンストラクトで構造化する 23 15 2023/05/20 AWS CDK CONFERENCE JAPAN © 2023, Amazon Web Services, Inc. or its affiliates. Twitter: #jawsug_cdk ೝূ Storage Lambda API ίϯετϥΫτͰίʔυΛߏ଄Խ͢Δ 14 ↑ίϨ͘Β͍ͷཻ౓Ͱ·ͱ·͍ͬͯΔͱύοτݟͰߏ଄͕Θ͔Γ΍͍͢ vs ίʔυྫ: aws-samples/websocket-api-cognito-auth-sample AWS CDK Best Practices https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html 公式 • 構造化の⼿段は スタックではなく コンストラクト （CloudFormation とは違う） • コンストラクトの 分け⽅に正解はない ← AWS CDKのあるあるお悩みに答えたい https://speakerdeck.com/tmokmss/answe ring-cdk-faqs?slide=15
23. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk ベタ書きからはじめる 静的であるほどテストは容易 • アプリのコードと異なり 動的に振る舞いを変える必要性が低い • コードとパラメータを⼀箇所で管理し 変更時には明⽰的にレビュー、ビルド、テスト • 必要になるまでパラメータ化しない 24 16 ベタ書きで ミスを回避する 環境ごとの変更が 必要になったら考える
24. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk パラメータは App レベルから注⼊する Stack や Construct から外部のパラメータを参照しない • クラスがテスト可能でなくなるため • main.ts や app.py などのエントリーポイント (CDK App を宣⾔) で 外部のファイルや環境変数からパラメータを受け取り、 Stack のプロパティで渡す • 「App は Stack をいい感じに宣⾔するスクリプト」と考えてもよい 25 17 App Stack Construct AWS リソース ファイルや 環境変数 props props AWS CDK Best Practices https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html 公式
25. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk スナップショットテストを書く • CloudFormation テンプレートの出⼒を⽐較して意図しない変更がないことを数⾏のコードで確認 • 条件分岐などのロジックやパラメータが必要になったらユニットテストを書く 26 18 実⾏結果 テストコード スナップショット（Git にコミットする）
26. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk リソース名ではなく Construct ID にこだわる 27 19 © 2023, Amazon Web Services, Inc. or its affiliates. All rights reserved. クラスの役割と物理名を考慮した命名の例 • Construct ID は PascalCase で命名する • 短くシンプルな名前で可視性を向上 • 共通の prefix をつけない（Construct による構造化で繰り返し出現するため） • リソースごとの制約によって切り詰められて末尾が失われないようにする • Stage の Construct ID には環境名をつける 例) Dev, Staging, Prod • Stack の Construct ID にはサービスの名前をつける 例) AwsomePhotos, Dev-GovBase • リソースの Construct ID にはシンプルな名前をつける 例) ItemTable 前提︓スタックは なるべく分割しない Stack より下には "-" などの区切り⽂字が⼊らない Dev-AwsomePhotos-ItemTableXXXXXXXX-XXXXXXXX prod-awsomephotos-userphotoslogbucketxxxxxxxx-xxxxxxxx Dev-AwsomePhotos Stage がない場合 "環境名-" を前置 • リソース名 = 物理名 = TableName など • シンプルな名前付けと タグでの検索を推奨 ← BLEA開発チームが学んだ AWS CDKの開発プラクティス 2023年版 https://speakerdeck.com/konokenj/blea- cdk-dev-practice-2023?slide=30
27. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk コードベースと環境の⼀貫性を保つ • 常にすべてのスタックをデプロイすることから始める $ cdk deploy --all • ⼀部だけデプロイする場合も全部の差分を継続的に確認 • テンプレートが同じならリソースの操作は⾏われない • ⼿でリソースを変更しない（変更したら必ずコードに反映する） 28 20 テスト環境 ステージング環境 本番環境 ⼀度だけビルド Git リポジトリ Consistency 参考︓CI/CD の原則 • パイプライン中で⼀度だけビルドする cdk deploy --app cdk.out で単⼀のアーティファクトを使⽤ • ⼤規模で複雑なマージを伴う⻑命なブランチを作らない https://www.atlassian.com/continuous-delivery/principles https://about.gitlab.com/blog/2022/02/03/how-to-keep-up-with-ci-cd-best-practices/ https://docs.aws.amazon.com/ja_jp/whitepapers/latest/ practicing-continuous-integration-continuous-delivery/summary-of-best-practices.html
28. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk 29 コミュニティに学び、 ⾃らも貢献しよう Learn and Be Curious
29. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk Thank you! 30 Kenji Kono @konokenj https://x.com/konokenj
30. © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. < #jawsug_cdk チームのつながりを Infrastructure as Code で デザインする 31 © 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. IaC でチーム作りの 5 つの障壁を乗り越える 分断したチーム ソフトウェアで継続的に 顧客に価値を届ける 変更を素早く提供し フィードバックループを回す End-to-end で 責任をもつチーム 周囲の理解と協⼒がない ü 環境の⼀貫性と⾃動化 ü すべてをコード化 ü チームの共通⾔語 ü 役割を越えて探索する ü 安全なセルフサービスを構築 AWS Summit Japan 2024 で IaC の価値に⽴ち戻り、 AWS CDK のプラクティスを 組織づくりに活⽤する話をしました https://pages.awscloud.com/rs/112-TZM-766/images/AWS-33_Builder-Experience_AWS_Summit_JP_2024.pdf