AWS CDK 入門まとめ：基本コマンドからベストプラクティスまで

はじめに

本記事は AWS が公式で公開している 「AWS CDK について学びたい方に向けたリソース」の内容を中心に、下記点についてまとめています。

1. CDK のコマンド
2. CDK API レファレンスの確認方法
3. 初心者がおさえておきたい AWS CDK のベストプラクティス

CDK を一通り学習したものの、使用機会が少なく忘れてしまうためにいざ開発！となった際にサクッと復習できるようにまとめました。

CDK のコマンド

1. Initialize

    # ディレクトリを作成 (ディレクトリ名を使⽤してファイル名や Stack 名を⽣成する）
    $ mkdir cdk-sample
    $ cd cdk-sample
    # CDK プロジェクトを作成
    $ npx aws-cdk init app --language=typescript
    # CDK Bootstrapping (CDKを対象アカウント、リージョンに初めてデプロイする場合のみ）
    $ npx aws-cdk bootstrap 
   

Tips: npx について
通常、CDKをグローバルにインストールしている場合は cdk init のようにコマンドを利用します。しかし、ローカルインストールの aws-cdk を使⽤する場合は npx aws-cdk init を使用する必要があります。

2. Code
   IDE やテキストエディタを使⽤して CDK アプリをコーディングする。

3. Test

    # CDK から CloudFormaiton template などを含む Cloud Assembly を合成
    $ npx aws-cdk synth
    # テスト (Jest などでテストの実装が必要)
    $ npm run test
   

   synthで生成された CloudFormation テンプレートは自動的に新規作成された cdk.out/ フォルダに出力され、エディタから確認できます。

4. Deploy

    # デプロイ済みの CloudFormation Template との差分を確認
    $ npx aws-cdk diff
    # AWS に CDK アプリをデプロイ
    $ npx aws-cdk deploy --all
   

   cdk deploy の代表的なオプション

   $ npx aws-cdk deploy SampleStack # スタックを指定してデプロイ
   $ npx aws-cdk deploy --all --require-approval=never # デプロイ時の確認を⾏わない
   $ npx aws-cdk deploy --all --no-rollback # スタックの更新失敗時に⾃動ロールバックしない
   

AWS CDK の API リファレンス の確認方法

1. AWS CDK の API リファレンス より実装したいリソース名を探し、Overview を確認する。ライブラリのimport文を転記する

2. 実装方法について詳しく知るために、Constructs 内から実装したいサービス名を確認する
   参考：VPC コンストラクトのドキュメントを確認する

3. Example や Initializer を参照して大まかな書き方を把握したら、Construct Props よりクラスをインスタンス化する方法を確認する
   例えば、 Vpc クラスをインスタンス化するための方法は下記の通り。

     new Vpc(scope: Construct, id: string, props?: VpcProps)
   

   • scope: Construct ツリーの親を指定。通常は現在のスコープを表す this になる。
   • id: Construct ID と呼ばれる。scope 内で⼀意となる識別⼦を指定。リソース名や論理 ID 論理 ID の⼀部になる。なお、Construct ID はItemTableのようにパスカルケース (PascalCase) にするのが良い。
   • props: Construct の初期状態を定義するプロパティ。適切なデフォルト値が⽤意されている。たとえば、ec2.Vpc コンストラクトはipAddresses、maxAzs、subnetConfiguration のようなプロパティを受け入れる。
   コンストラクタとは

   • クラスからインスタンスが生成された直後に自動実行される処理をあらかじめ定義できるもの
   • コンストラクタの例

   class Person {
     firstName: string;
     lastName: string;
     // コンストラクタを定義
     constructor(firstName: string, lastName: string) {
       this.firstName = firstName;
       this.lastName = lastName;
     }
     greet() {
       console.log(`私は ${this.firstName} ${this.lastName} です。`);
     }
   }
   
   // クラスからオブジェクトを生成する際、引数を渡してプロパティを初期化
   const taro = new Person("AWS", "太郎");
   taro.greet();
   

4. 適切なプロパティを設定し、実装する
   下記のCDKコードの例では、2AZ にまたがり、それぞれパブリックサブネット・プライベートサブネットを 1 つずつ持つ VPC の設定が完了する。

   import { Stack, StackProps } from 'aws-cdk-lib';
   import { Construct } from 'constructs';
   // ec2 に関するパッケージを import
   import * as ec2 from "aws-cdk-lib/aws-ec2";
   
   export class CdkWorkshopStack extends Stack {
     constructor(scope: Construct, id: string, props?: StackProps) {
       super(scope, id, props);
   
       // vpc を宣言
       const vpc = new ec2.Vpc(this, "MyVpc", {
         ipAddresses: ec2.IpAddresses.cidr('10.0.0.0/16'),
       });
     }
   }
   

AWS CDK のベストプラクティス

初心者がおさえておきたい AWS CDK のベストプラクティスとして、下記20項目が紹介されています。

この中から「AWS CDK の基本」以降の内容を一部抜粋しつつ、補足します。

11. リソースの置き換えに注意する

• cdk diff や変更セットで変更を確認する
• 論理 ID の変更に注意する⚠️
  Construct ID (コンストラクタの第2引数に指定する文字列) を変更したり、Construct を別の階層に移動したりすると論理 ID が変わり必ず置き換えになる
• SSM Parameter など、CDK の外部で変更される値に注意する⚠️

13. grant / metric / connections を使う

• grant : AWSリソースに対するアクセス許可を設定するためのメソッド
  例) S3バケットに対して、Lambda関数が読み取りアクセスを持つようにする場合

  bucket.grantRead(lambdaFunction);
  

• metric : CloudWatchメトリクスを作成するためのメソッド
  例) S3バケットのオブジェクト数などをトラッキングする場合

  const metric = myBucket.metric('NumberOfObjects');
  

• connections : AWSリソース間のネットワーク接続を管理するためのプロパティ
  例) fleet2 -> fleet1 に任意の通信を許可する場合

  fleet1.connections.allowFrom(fleet2, ec2.Port.AllTraffic());
  

14. 必要になるまでスタックは分けない

• 基本ルール: 必要がないなら分けない。構造化の手段は「スタック」ではなく「コンストラクト」を使うこと（15. の項目にて補足）
• スタック分割を考える場合
  参考：AWS CDK Tips: スタックの分け方について

15. コンストラクトで構造化する

• それぞれのリソースを適切な粒度でまとめた自作のコンストラクトを作り、それらを他のCDKコードから呼び出すようにする
  
  引用：AWS CDKのあるあるお悩みに答えたい
  参考：AWS CDK Tips: コンストラクトで構造化しよう

17. パラメータは App レベルから注入する

• Stack や Construct から外部のパラメータを参照しない
• CDK App を宣言する CDK のエントリポイントで外部のファイルや環境変数からパラメータを受け取り、Stack のプロパティで渡すようにする
  参考： CDKのデプロイ先アカウントはどう定義すればいいの？

18. スナップショットテストを書く

• スナップショットテストとは、事前に記録された スナップショットに対して、テスト実行時の実装から作成した CloudFormation のテンプレートを検証（比較）すること。jest など各言語固有のテストコマンドで実行。
  
  参考：AWS CDKv2 でスナップショットテストと CI を始めてみよう

19. リソース名でなく Construct ID にこだわる

• Stage の Construct ID には環境名をつける
  例) Dev, Staging, Prod
• Stack の Construct ID にはサービスの名前をつける。Stage がない場合は"環境名-" を前置する。
  例) AwsomePhotos, Dev-GovBase
  参考：AWS CDK で構築するリソースに 環境名 を入れる

さいごに

CDK の知識は、AWS BlackBelt の資料でインプット→ AWS WORKSHOP でアウトプットの流れで学習を進めましたが、資料も豊富かつわかりやすく大変お世話になりました。
本記事は私の備忘録としてピックアップさせて頂いたものになりますが、是非公式サイトをご覧ください🙇‍♀️

以上、どなたかの参考になれば幸いです。
えみり〜でした|ωΦ)ฅ

参考

• AWS CDK とは
• 初心者がおさえておきたいAWS CDKのベストプラクティス 2024
• AWS CDKでクラウドアプリケーションを開発するためのベストプラクティス
• CDK Pipelines: AWS CDK アプリケーションの継続的デリバリ
• AWS CDKのチーム開発時に実装時の考慮事項、意識合わせした点について