【第1回】AWS CDK × Python インフラ自動化入門 — IaCの基本とCDKプロジェクトのセットアップ

AWSのリソース管理をYAMLで書くのがしんどくなってきたので、CDKを本腰入れて使い始めました。このシリーズでは全4回にわたって、AWS CDKをPythonで使う方法をゼロから整理していきます。

シリーズ全体の流れはこんな感じです：

• 第1回（今回）：IaCの基本概念とCDKプロジェクトのセットアップ
• 第2回：ConstructsとStackの設計パターン
• 第3回：Lambda + DynamoDB + API Gatewayを一気にデプロイする
• 第4回：GitHub Actionsと組み合わせてCI/CDパイプラインを作る

第1回はとにかく「動かす」ことを目標に、概念の整理からプロジェクト作成・初回デプロイまでをまとめます。

この記事でわかること

• IaC（Infrastructure as Code）の基本概念
• CDKが他のツール（CloudFormation、Terraformなど）とどう違うのか
• CDKのアーキテクチャ（App・Stack・Construct）の理解
• AWS CDK環境のセットアップ方法
• 初回デプロイまでの流れ（synth → bootstrap → deploy）
• デプロイ後の差分確認と削除方法

IaCとは何か、なぜCDKなのか

IaC（Infrastructure as Code）は、サーバーやネットワークといったインフラをコードで定義・管理するアプローチです。手作業でコンソールをポチポチする代わりに、コードをリポジトリで管理して再現性を担保できます。

AWSでIaCを実現するツールはいくつかあって、代表的なのはこのあたり：

• CloudFormation：AWSネイティブ。YAML/JSONでリソースを定義する
• Terraform：マルチクラウド対応。HCLという独自言語を使う
• AWS CDK：PythonやTypeScriptなど普通のプログラミング言語で書いて、最終的にCloudFormationに変換される
• AWS SAM：サーバーレス特化のCloudFormationラッパー

CloudFormationのYAMLを長年書いてきたんですが、正直つらい。100行超えると頭の中で構造が追えなくなるし、コピペして微妙にキーを間違えてエラーが出る、みたいなことが何度もあって。

CDKの何がうれしいかというと、普通のPythonとして書けるので、変数・ループ・関数・クラスが全部使えます。「dev環境とprod環境でS3バケット名だけ変えたい」みたいなケースを、if文1行で解決できるのは地味に大きいです。

余談ですが、TerraformとCDKのどっちを使うべきかという話題はよく見かけます。個人的にはAWS専用ならCDK、マルチクラウドならTerraformかなと思っていますが、組織によっては混在して使っているケースもあるらしいです。

AWS CDKのアーキテクチャを頭に入れておく

CDKを使い始める前に、構成要素を整理しておきます。知らずに進むと後でハマるので。

App → Stack → Construct の階層

CDKのコードは、大きく3つの概念で構成されています。

• App：CDKアプリ全体のルート。app.py に書く
• Stack：CloudFormationの「スタック」に相当。デプロイの単位
• Construct：AWSリソースを表すコンポーネント。S3バケット1個もConstructだし、複数リソースをまとめたカスタムモジュールもConstruct

Constructにはレベルがあって、これを知っておくとドキュメントを読むときに迷わなくなります。

• L1（Cfn〜）：CloudFormationリソースを1:1でラップしたもの。CfnBucket みたいなクラス名。プロパティ全指定が必要でほぼYAMLと同じ感覚
• L2：AWSが用意した高レベルな抽象。デフォルト値が設定されていて、ベストプラクティスを反映した書き方ができる。普段の開発ではここを一番使う
• L3（Patterns）：複数のL2をまとめた、よく使われる構成パターン。aws_solutions_constructs ライブラリにいろいろある

最初はL2を中心に覚えていけば十分だと思います。

CDKとCloudFormationの関係

CDKはあくまでCloudFormationのフロントエンドです。cdk synth を実行するとPythonコードからCloudFormationテンプレートが生成されて、それを使ってデプロイが走ります。デプロイ自体はCloudFormationがやってくれています。

なので、CDKを使ってもAWSコンソールのCloudFormationのページにはちゃんとスタックが出てきます。何かおかしいときはそっちを見に行くのが大事です（最初しばらくそれを忘れてて無駄に悩みました）。

環境のセットアップ

必要なものはこれだけです。

• Node.js（CDK CLIがNode製なので必須）
• Python 3.8以上
• AWS CLIとアカウントの認証設定

Node.jsは直接CDKのコードを書くわけじゃなくても必要なので注意です。バージョンは特に細かい指定はないですが、LTSを使っておくのが無難です。

CDK CLIのインストール

# CDK CLIをグローバルにインストール
npm install -g aws-cdk

# バージョン確認
cdk --version

現在はv2系が現行です。cdk --version で 2.x.x と表示されればOKです。

プロジェクトの初期化

mkdir my-cdk-app
cd my-cdk-app

cdk init app --language python

このコマンドを実行すると、こんなディレクトリ構成が生成されます。

my-cdk-app/
├── app.py                  # Appのエントリポイント
├── cdk.json                # CDKの設定ファイル
├── requirements.txt        # Pythonの依存関係
├── requirements-dev.txt
├── source.bat
├── .venv/                  # （自動生成される仮想環境）
└── my_cdk_app/
    ├── __init__.py
    └── my_cdk_app_stack.py # メインのStackクラス

仮想環境を有効化して依存関係をインストールします。

source .venv/bin/activate

pip install -r requirements.txt

Windowsの場合は .venv\Scripts\activate.bat です。

初期コードを読んでみる

生成されたコードをそのまま眺めてみます。

app.py：

import aws_cdk as cdk
from my_cdk_app.my_cdk_app_stack import MyCdkAppStack

app = cdk.App()
MyCdkAppStack(app, "MyCdkAppStack")

app.synth()

my_cdk_app_stack.py（デフォルト生成）：

from aws_cdk import Stack
from constructs import Construct

class MyCdkAppStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # ここにリソースを定義していく

シンプルです。Stack クラスを継承して、__init__ の中にリソースを追加していくスタイルです。Pythonを普通に書く感覚でいけます。

試しにS3バケットを1個作ってみましょう。

from aws_cdk import (
    Stack,
    aws_s3 as s3,
    RemovalPolicy,
)
from constructs import Construct

class MyCdkAppStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        s3.Bucket(
            self,
            "MyFirstBucket",
            bucket_name="my-first-cdk-bucket-20260701",
            versioned=True,
            block_public_access=s3.BlockPublicAccess.BLOCK_ALL,
            removal_policy=RemovalPolicy.DESTROY,  # ここ注意: デフォルトはRETAIN
        )

RemovalPolicy.DESTROY にしておかないと、スタックを削除してもバケットが残り続けます。学習目的ならDESTROYが楽ですが、本番では要検討です。

synthesize → bootstrap → deploy の流れ

コードが書けたら実際に動かしてみます。3ステップです。

1. cdk synth でテンプレート確認

cdk synth

CloudFormationのJSONテンプレートが標準出力に出てきます。デプロイ前に何が作られるかを確認できるので、習慣的に実行するといいです。エラーがここで出たらコードのミスです。

2. cdk bootstrap（初回のみ）

cdk bootstrap aws://123456789012/ap-northeast-1

初回だけ実行すればOKで、CDKが内部で使うS3バケット（アーティファクト置き場）やIAMロールをAWS側に用意してくれます。これをやらずにデプロイしようとするとエラーになります。最初は何故かここで詰まりがちです。

3. cdk deploy

cdk deploy

IAMに関する変更が含まれる場合は確認を求められます。--require-approval never をつけると省略できますが、最初は内容を確認しながら進むのがいいと思います。

デプロイが成功すると、AWSコンソールのCloudFormationにスタックが作られているのを確認できます。

差分確認と削除

CDKを使うなら cdk diff も覚えておくと便利です。

cdk diff

現在デプロイ済みのスタックと、ローカルのコードの差分を出してくれます。「何を変えようとしているか」を事前に確認できるので、本番環境への適用前に必ず叩くようにしています。

スタックを全部消したいときは：

cdk destroy

確認プロンプトが出るので、y を入力すればスタックごと削除されます。RemovalPolicy.DESTROY を指定したリソースはまとめて消えます。

※この記事にはプロモーションが含まれます

ちなみに、お名前.com レンタルサーバー（WordPressに特化した高速レンタルサーバー。月額990円〜、独自ドメイン実質0円）も気になっています。お名前.com レンタルサーバー

まとめ

第1回はここまでです。IaCの概念、CDKの構成要素、プロジェクトのセットアップ、そして初回デプロイの流れをひと通り確認しました。

正直、慣れるまでは「なんでNode.jsが必要なの」「bootstrapって何してるの」みたいな疑問が出てくると思いますが、まずは一度手を動かして動かしてみるのが一番早いです。次回は、Constructsとその設計パターンについて掘り下げていく予定です。