AWS CDK 入門ガイド これだけは知っておきたいヒント集

チェック

• [ ] 本文を確認した
• [ ] 概要を確認した
• [ ] タグを確認した
• [ ] inbox/ 直下へ移行した

概要

AWS CDK の基本概念、初期化からデプロイまでの流れ、Construct のレベル、テスト、ドキュメントの読み方、開発補助機能、生成 AI 連携までを整理した入門資料。 CDK はプログラミング言語で AWS インフラを定義し、CloudFormation template を生成するフレームワーク。 App、Stack、Construct、Cloud Assembly、bootstrap、synth、diff、deploy の流れを理解するための実務向けガイド。

本文

資料は、AWS CDK を初めて使う人に向けて、IaC の基本から CDK の開発体験、運用時のヒントまでを説明している。

IaC と CDK

IaC、Infrastructure as Code は、インフラをコードで定義し、再現可能に管理する考え方。 手作業でコンソールからリソースを作るのではなく、コードに desired state を書き、ツールで適用する。 これにより、レビュー、履歴管理、再現性、環境差分の管理、CI/CD との連携がしやすくなる。

AWS CDK は、TypeScript、JavaScript、Python、Java、.NET、Go などのプログラミング言語で AWS リソースを定義し、最終的に CloudFormation template を生成する OSS フレームワーク。 CloudFormation を直接 YAML/JSON で書く代わりに、プログラミング言語の型、関数、クラス、補完、テストを使える。

CDK の利点

CDK の利点として、資料では開発者体験が強調される。

プログラミング言語の型や IDE 補完によって、プロパティ名の間違いや必須項目の漏れに気づきやすい。 Construct がリソース間の依存関係を解決してくれるため、手動で DependsOn を書く場面が減る。 アプリケーションの asset、たとえば Lambda code や Docker image も CDK のデプロイフローに組み込める。

また、抽象化された Construct によってデフォルト設定やベストプラクティスを再利用できる。 組織独自の Construct を作れば、セキュリティやタグ、監視などのガードレールを埋め込める。 必要な場合は escape hatch を使い、低レベルの CloudFormation 設定へ降りることもできる。

App、Stack、Construct、Cloud Assembly

CDK アプリケーションの基本要素は App、Stack、Construct。

App は CDK アプリケーション全体。 複数の Stack を含められる。

Stack は CloudFormation Stack に対応する単位。 リージョン、アカウント、リソースのデプロイ単位になる。

Construct は CDK の構成要素。 S3 Bucket、SQS Queue、VPC、Lambda Function など、個々のリソースや複数リソースのパターンを表す。

Cloud Assembly は、CDK が synth した結果の成果物。 CloudFormation template や asset 情報などが含まれる。

Construct のレベル

Construct には複数のレベルがある。

L1 Construct は CloudFormation resource にほぼ 1:1 対応する。 CfnBucket のような名前になり、CloudFormation の全機能に近いが、記述は低レベル。

L2 Construct は AWS リソースを使いやすくした高レベル Construct。 たとえば s3.Bucket や sqs.Queue のように、便利なデフォルトや helper method を持つ。

L3 Construct は複数リソースを組み合わせた pattern。 よくある構成をまとめ、より少ないコードで利用できる。

資料では、必要に応じて L1、L2、L3 を使い分け、足りない部分は escape hatch で補えることが説明される。

TypeScript プロジェクトの初期化

TypeScript で CDK アプリを始める基本手順は次の通り。

mkdir sample-app
cd sample-app
npx aws-cdk init app --language=typescript

生成されるファイルには、bin/、lib/、test/、cdk.json、package.json、jest.config.js などが含まれる。

代表的な構成は次のようなもの。

README.md
bin/sample-app.ts
lib/sample-app-stack.ts
test/sample-app.test.ts
cdk.json
package.json
tsconfig.json
jest.config.js

bin/ には App のエントリーポイント、lib/ には Stack 定義、test/ には CDK template のテストを書く。

bootstrap、synth、diff、deploy

CDK をデプロイする前に、対象アカウント・リージョンへ bootstrap が必要になる。

npx aws-cdk bootstrap

bootstrap は CDKToolkit Stack を作り、asset 用 S3 Bucket、ECR repository、IAM Role など、CDK デプロイに必要なリソースを用意する。 アカウント・リージョンごとに必要。

template を生成するには synth。

npx aws-cdk synth

差分を見るには diff。

npx aws-cdk diff

デプロイするには deploy。

npx aws-cdk deploy

テストは通常の npm script として実行できる。

npm run test

Stack の例

簡単な Stack では、S3 Bucket と SQS Queue を作る。

import { Stack } from "aws-cdk-lib";
import { Construct } from "constructs";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as sqs from "aws-cdk-lib/aws-sqs";

export class SampleAppStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new s3.Bucket(this, "HogeBucket");
    new sqs.Queue(this, "HogeQueue");
  }
}

CDK はこの TypeScript コードから CloudFormation template を生成する。

CDK のテスト

CDK には複数のテスト方法がある。

Snapshot test は、生成される template 全体を snapshot として保存し、意図しない差分を検出する。 CDK や Construct の変更で template が変わったときに気づける。

Fine-grained assertion は、特定の resource type や property が存在するかを検証する。

Validation test は、Construct の入力値や制約を確認する。

Integration test は、実際に AWS 環境へデプロイして動作を見る。

Policy validation は、IAM やセキュリティポリシーの検証に使う。

入門では、まず snapshot と assertions を使うとよい。

ドキュメントの読み方

CDK では API Reference と Developer Guide が重要。 API Reference では、サービスライブラリ、Construct の概要、例、引数、メソッドを確認する。

たとえば S3 Bucket を調べるなら、aws-cdk-lib/aws-s3 の overview を読み、Bucket construct の props、method、example を見る。 CloudFormation resource との対応が必要な場合は L1 Construct も確認する。

aws-cdk-examples も参考になる。 実際の構成例から、Construct の組み合わせや推奨パターンを学べる。

AWS Toolkit と高速開発

AWS Toolkit for VS Code では、CDK Stack や resources をエディタ上で見られる。 tree.json を使って CDK construct tree を可視化でき、AWS credentials なしでも構造確認に使える場合がある。

cdk watch は、ファイル変更を検知して再デプロイする。 cdk deploy --hotswap は、一部変更を CloudFormation 経由ではなく直接更新し、開発速度を上げる。 ただし hotswap は experimental で、CloudFormation の state と drift が起きる可能性があるため、本番ではなく開発用に使う。

生成AIとの連携

資料では、Amazon Q Developer、AWS CDK MCP Server、AWS Documentation MCP Server、Generative AI CDK Constructs、Amplify AI Kit などにも触れる。 CDK はコードとしてインフラを扱うため、生成 AI と相性がよい。

ただし、AI が生成した CDK は必ず synth、diff、test で確認する。 公式ドキュメントや MCP から最新情報を参照し、古い API や危険なデフォルトを避ける必要がある。

要点

• CDK はプログラミング言語で AWS インフラを定義し、CloudFormation template を生成する。
• 基本要素は App、Stack、Construct、Cloud Assembly。
• Construct には L1、L2、L3 があり、抽象度に応じて使い分ける。
• TypeScript では npx aws-cdk init app --language=typescript から始められる。
• bootstrap はアカウント・リージョンごとに必要。
• synth、diff、deploy、test を開発フローに組み込む。
• Snapshot と Assertions は CDK の品質ゲートとして重要。
• cdk watch や hotswap は開発向けで、本番適用には注意が必要。

タグ

aws-cdk #iac #cloudformation #typescript #testing