第0章 この資料のゴール
あなたが最終的に「なるほど！」と言えるようにしたいのは、次の1文です。
「TypeScript で書いたコードを
cdk deployすると、AWS 上にサーバーやデータベースが自動で建ち、
その後はコードを Git に push するだけで、アプリが自動で更新される」
この1文を、分解しながら理解していきます。あせらず、上から順に読んでください。
途中の専門用語はすべて、あとで「たとえ話」とセットで説明します。
第1章 そもそもの大前提（ここを飛ばさない）
1-1. サーバーって何？
あなたが使っている Web アプリ（ブラウザで開く画面）は、実は どこかのコンピュータの上で動いています。
このコンピュータのことを サーバー と呼びます。
- あなたの手元の PC = クライアント（使う側）
- どこかで24時間動いている PC = サーバー（提供する側）
昔は、会社が自分で物理的なコンピュータ（鉄の箱）を買ってきて、電源を入れて、ケーブルをつないで…
としていました。これは大変です。壊れたら買い直し、性能が足りなくなったら増設…。
1-2. クラウド（AWS）って何？
そこで登場したのが クラウド です。代表例が AWS（Amazon Web Services） です。
クラウドをひとことで言うと：
「コンピュータやデータベースを、買うのではなく "借りる" 仕組み」
しかも、ネット越しに「コンピュータ1台ちょうだい」「データベース1個ちょうだい」と
注文すれば数分で用意してくれる レンタルサービスです。
このシステムは、この AWS の上に建っています。
1-3. AWS で「借りられる部品」の例
AWS にはたくさんの「部品（サービス）」があります。このシステムで使っている主なものだけ紹介します。
（今は「へぇ、こういう部品があるんだ」程度でOK。あとで何度も出てきます）
| AWS の部品 | これは何？ | 家にたとえると |
|---|---|---|
| VPC | あなた専用の仮想ネットワーク（土地・区画） | 家を建てる「土地」 |
| EC2 / Fargate / ECS | プログラムを動かすコンピュータ | 家の「部屋」 |
| RDS | データベース（データの保管庫） | 「金庫」 |
| ElastiCache (Valkey/Redis) | 一時的な高速メモリ保管 | 「冷蔵庫（すぐ取り出す用）」 |
| S3 | ファイル置き場（写真・書類など） | 「物置・倉庫」 |
| ALB | アクセスを振り分ける受付係 | 「玄関の受付」 |
| CloudFront / CDN | 世界中に配信を速くする仕組み | 「全国の配送拠点」 |
| Cognito | ログイン・ユーザー管理 | 「鍵と入館証の管理人」 |
| Bedrock | AI（Claude など）を呼び出すサービス | 「相談できる専門家」 |
| Lambda | 短い処理をサッと実行する小型実行環境 | 「呼べば来る便利屋さん」 |
| SQS | 仕事を順番待ちさせる行列 | 「順番待ちの整理券」 |
このシステムは、これらの部品を 何十個も組み合わせて できています。
第2章 ここが核心：「手作業」と「コードで自動化」の違い
2-1. 手作業だと何が問題か
第1章の部品を、AWS の管理画面（マウスでポチポチする画面）から手で作ることもできます。
でも、それには大問題があります。
- 間違える：ポチポチ作業は、設定を1つ押し間違えるだけで動かなくなる
- 再現できない：「開発環境とまったく同じものを本番にも作って」と言われても、手順を覚えていない
- 記録が残らない：誰がいつ何を変えたのか分からない
- 時間がかかる：何十個の部品を毎回手で作るのは地獄
2-2. そこで「コードで書く」= IaC
この問題を解決するのが IaC（Infrastructure as Code / インフラをコードで書く） という考え方です。
「どんな部品を、どう組み合わせて作るか」を、文章（コード）として書いておく。
あとはそのコードを実行すれば、AWS が自動でその通りに作ってくれる。
料理にたとえると：
- 手作業 = 毎回「勘」で料理する（味が安定しない、人に伝えられない）
- IaC = レシピを書いておく（誰がやっても同じ料理ができる、改良の履歴も残る）
このシステムは、すべて「レシピ（コード）」で書かれています。 だから手で作った部品はほぼありません。
第3章 CloudFormation と CDK
3-1. CloudFormation = AWS 公式のレシピ形式
AWS には「IaC のための公式のレシピ形式」があります。それが CloudFormation です。
CloudFormation は、「どんな部品を作るか」を書いた巨大な設計図ファイル（テンプレート）を読み込んで、
その通りに AWS の部品を一気に作ってくれます。
ただし問題があります。CloudFormation のテンプレートは、書くのがとても面倒くさいのです。
JSON や YAML という形式で、何千行も手で書く必要があり、人間には読み書きが大変です。
3-2. CDK = レシピを「プログラミング言語」で書ける道具
そこで登場するのが、ついにこの資料の主役、CDK（Cloud Development Kit） です。
CDK とは「TypeScript などの普通のプログラミング言語で AWS のレシピを書ける道具」です。
CDK を使うと：
- あなたは TypeScript で「VPC を作る」「データベースを作る」と短く書く
- CDK がそれを、AWS が理解できる CloudFormation のテンプレート（巨大な設計図）に自動翻訳 する
- そのテンプレートを AWS に渡すと、部品が実際に建つ
つまり CDK は 「人間が書きやすい言葉 → AWS が分かる言葉」への翻訳機 です。
あなたが書く CDK が翻訳 AWS が実行
TypeScript のコード ──▶ CloudFormation ──▶ 実際のサーバー・DB が建つ
（短くて読みやすい） （巨大な設計図） （クラウド上の本物）
3-3. 「synth」と「deploy」という2つの動作
CDK を触ると、必ずこの2つの言葉が出てきます。ここだけ覚えてください。
| コマンド | 何をする？ | たとえ |
|---|---|---|
cdk synth |
TypeScript を CloudFormation の設計図に翻訳するだけ（まだ作らない） | レシピを「清書」する |
cdk deploy |
翻訳した設計図を AWS に渡して実際に建てる | レシピ通りに「料理する」 |
cdk diff |
「今ある状態」と「コードの状態」の違いを見る | 「前と何が変わった？」を確認 |
第4章 「スタック」という単位 ― CDK の部屋割り
CDK では、部品をいくつかの スタック（Stack） というグループに分けて管理します。
スタック = 関連する部品をまとめた「ひとかたまり」。
CloudFormation はこのスタック単位で「作る・更新する・消す」を行います。
家を建てる作業にたとえると、こんなふうにグループ分けします。
- 「土地・ネットワーク」のスタック
- 「データベース」のスタック
- 「アプリ本体」のスタック
- 「配信（CDN）」のスタック
分けておくと、「データベースだけ作り直す」「アプリだけ更新する」が安全にできます。
4-1. bin/ と lib/ の関係（実際のフォルダ構成）
CDK プロジェクトのフォルダには、必ず bin と lib があります。
-
lib/フォルダ = スタック1個ずつの「設計図の中身」が入っている（部品の作り方） -
bin/フォルダ = それらのスタックを「どの順で、どの環境に建てるか」を指揮する司令塔
料理でいうと、lib/ が「各料理のレシピ集」、bin/ が「今日のコース料理の組み立て表」です。
第5章 このシステムの全体像 ― CDK プロジェクトは「2つ」ある
ここが、あなたが混乱しやすい最重要ポイントです。
このシステムには、役割の違う CDK プロジェクトが2つあります。
projects/
├── infra-cdk/ ← ① インフラ本体を建てる（家そのもの）
└── pipeline-cdk/ ← ② CI/CD を建てる（自動更新の仕組み）
| プロジェクト | 役割 | たとえ |
|---|---|---|
| infra-cdk | アプリが動くための 箱（サーバー・DB・ネットワークなど）を建てる | 家を建てる |
| pipeline-cdk | コードが変わったら 自動でアプリを更新する仕組みを建てる | 家に自動配達システムを取り付ける |
※ もう1つ
appというフォルダがありますが、これは アプリの中身（実際のプログラム本体） です。
CDK（インフラのレシピ）ではなく、「家の中で動くアプリそのもの」だと思ってください。
それぞれを順に見ていきます。
第6章 ① infra-cdk ― 「家を建てる」CDK
これは「アプリが動くための土台」を全部建てるプロジェクトです。
司令塔ファイル bin/infra-cdk.ts を見ると、建てる順番 がそのまま書いてあります。
実際に建てられるスタックは、おおよそ次の順番です（bin/infra-cdk.ts より）。
| 順番 | スタック名 | 何を作る？ | たとえ |
|---|---|---|---|
| 1 | NetworkStack | VPC（専用ネットワーク） | 土地・区画整理 |
| 2 | SecurityGroupStack | 通信のルール（誰が入れるか） | 塀とゲート |
| 3 | BedrockStack | AI（Claude）を呼ぶ設定 | 相談できる専門家を契約 |
| 4 | DatabaseStack | RDS（DB）と Valkey（高速メモリ） | 金庫と冷蔵庫 |
| 5 | S3Stack | ファイル置き場 | 物置 |
| 6 | RoleStack | 権限（誰が何をしてよいか） | 役割と権限証 |
| 7 | AuthorizationStack | Cognito（ログイン管理）※注 | 入館証の管理人 |
| 8 | IdentityPoolStack | ログインユーザーの権限割当 ※注 | 入館証に応じた鍵配り |
| 9 | BatchStack | 非同期のバッチ処理基盤 | 専用の作業部屋 |
| 10 | ApplicationStack | アプリ本体（フロントエンド・バックエンド・AI処理） | 家のメインの部屋 |
| 11 | CdnStack | CloudFront（高速配信）※別リージョン | 全国配送拠点 |
※注：7番・8番（Cognito 関連）は、staging / production だけで自動作成されます。
develop 環境では「すでに手で作った Cognito」を使い回すため、コードでは作りません。
（bin/infra-cdk.tsのif (existingUserPoolId && existingAppClientId)がこの分岐です）
6-1. スタックが「つながっている」とはどういうことか
ここで大事なのが、スタック同士はバラバラではなく、つながっているということです。
たとえば bin/infra-cdk.ts を見ると、こう書かれています（簡略化）：
const network = new NetworkStack(...); // まずネットワークを作る
const database = new DatabaseStack({ vpc: network.vpc, ... }); // そのネットワークの中にDBを作る
const application = new ApplicationStack({ vpc: network.vpc, dbSecret: database... }); // DBに繋ぐアプリを作る
network.vpc のように、前に作った部品を次の部品に渡しているのが分かります。
これにより CDK は「ネットワーク → DB → アプリ」という 正しい順番 を自動で判断してくれます。
（DB を作る前にアプリは作れない、というような依存関係を自動管理）
第7章 「環境」という考え方 ― 同じ家を3軒建てる
7-1. なぜ環境を分けるのか
ソフトウェア開発では、いきなり本番（利用者が使う場所）で試すのは危険です。
そこで、同じ構成の "場所" を複数用意します。これを 環境（environment） と呼びます。
このシステムには3つの環境があります。
| 環境名 | 用途 | たとえ |
|---|---|---|
| develop（dev） | 開発者が日々試す場所 | 練習用のグラウンド |
| staging（stg） | 本番直前の最終確認の場所 | リハーサル会場 |
| production（prod） | 本物の利用者が使う場所 | 本番の試合会場 |
3つとも、ほぼ同じ部品構成です。 違うのは「どのAWSアカウントに建てるか」「設定値（URLや名前）」だけ。
7-2. 設定ファイル（YAML）で切り替える
「3環境ぶんのコードを3回書く」のは無駄です。そこで、部品の作り方（コード）は1つだけ書いて、
環境ごとに違う値は YAML ファイルに分けて あります。
infra-cdk/config/
├── develop.yml ← dev 用の設定値
├── staging.yml ← stg 用の設定値
└── production.yml ← prod 用の設定値
たとえば config/develop.yml には、こう書かれています（抜粋・アカウント番号はダミー）：
environment: develop
accounts:
deployments: "111122223333" # CI/CD を動かすアカウント
workloads: "222233334444" # アプリ本体が動くアカウント
rds:
engineVersion: "17.6" # データベースのバージョン
コマンド実行時に -c env=develop のように「どの環境か」を指定すると、
CDK は対応する YAML を読み込んで、その値で部品を建てます。
npx cdk deploy --all -c env=develop # dev に建てる
npx cdk deploy --all -c env=staging # stg に建てる
npx cdk deploy --all -c env=production # prod に建てる
同じレシピ（コード）＋ 違う調味料（YAML）＝ 3つの環境、というイメージです。
7-3. アカウントが2種類あるのはなぜ？（重要）
YAML をよく見ると、アカウント番号が 2種類 あります。
- Deployments アカウント = CI/CD（自動更新の仕組み）を動かす場所
- Workloads アカウント = アプリ本体が実際に動く場所（環境ごとに別アカウント）
なぜ分けるのか？ 安全のためです。
「ビルドや配達を担当する作業場（Deployments）」と「利用者が触る本番の家（Workloads）」を
別の建物にしておけば、片方で事故っても、もう片方を守れます。
この2つをつなぐのが WorkloadDeployRole（次の章に出てきます）という「通行許可証」です。
CI/CD 側が、この許可証を使って Workloads 側に入って更新作業をします。
第8章 ② pipeline-cdk ― 「CI/CD（自動更新）」を建てる CDK
ここからが、もう一つの主役 CI/CD です。
8-1. CI/CD とは何か
- CI（継続的インテグレーション） = コードが変わるたびに自動でチェック・テストする仕組み
- CD（継続的デリバリー/デプロイ） = チェックを通ったコードを自動で環境に届ける仕組み
ひとことで言うと：
「コードを保存（push）するだけで、検査 → 組み立て → 設置 まで全部自動でやってくれるベルトコンベア」
これがないと、人間が毎回手で「ビルドして、アップロードして、サーバーを再起動して…」を
やらなければなりません。CI/CD はそれを全自動にします。
8-2. CI/CD を構成する AWS の部品
| 部品 | 役割 | たとえ |
|---|---|---|
| CodeCommit | ソースコードの保管庫（Git） | 設計図の保管室 |
| CodeBuild | コードを組み立て・テストする作業員 | 工場の組み立てライン |
| CodePipeline | 全工程をつなぐベルトコンベア | 工場全体の指揮者 |
| ECR | 作ったアプリ（Dockerイメージ）の倉庫 | 完成品の倉庫 |
| ECS / Fargate | アプリを実際に動かす場所 | 完成品を設置する店舗 |
8-3. このシステムのパイプライン構成（実物）
pipeline-cdk/bin/pipeline-cdk.ts を見ると、次のスタックが建てられます。
| スタック | 役割 |
|---|---|
| PipelineNetworkStack | パイプライン作業用のネットワーク |
| RepositoryStack | CodeCommit（コード倉庫）と ECR（イメージ倉庫）を作る |
| PipelineDevStack | 本体のパイプライン（後述のベルトコンベア） |
| PipelineInitStack | 初期セットアップ用のパイプライン |
| PipelinePrCiStack | PR（修正提案）のときに自動検査するゲート（dev/stg のみ） |
8-4. ベルトコンベアの中身（PipelineDevStack のステージ）
メインのパイプライン PipelineDevStack は、4つのステージ（工程） を順番に流れます。
（lib/pipeline-dev-stack.ts の new codepipeline.Pipeline(...) 部分）
[1] Source [2] ContainerBuild [3] FunctionsUpdate [4] DbMigration
コードを取得 ──▶ アプリを組み立てて ──▶ Lambda や ──▶ データベースの
(CodeCommit) 倉庫(ECR)へ入れ、 StepFunctions、 構造を最新化
店(ECS)を入れ替え S3ファイルを更新 (alembic)
各ステージで何をしているか、もう少しだけ具体的に：
-
[1] Source：CodeCommit の
developブランチから最新コードを取り出す。
IsAutoDeploy: trueなら、push されたら自動でコンベアが動き出す（develop は自動）。 -
[2] ContainerBuild：フロントエンド・バックエンド・AI処理・バッチ処理を Docker でビルドし、
ECR（倉庫）に push。そのあと ECS のサービスを「新しいイメージで入れ替えろ」と命令する
（aws ecs update-service --force-new-deployment）。 - [3] FunctionsUpdate：Lambda 関数、Step Functions、S3 上のプロンプトファイルなどを更新。
-
[4] DbMigration：データベースの表の構造を最新のコードに合わせる（
alembic upgrade head）。
8-5. 「buildspec」= 作業員への作業指示書
CodeBuild（作業員）が「具体的に何のコマンドを打つか」は buildspec という指示書に書かれています。
このシステムでは2つの書き方が混在しています。
-
app/buildspec*.yml… ファイルとして置かれている指示書（おもに CI 検査用）。
例：buildspec_ci_be_test.yml（バックエンドのテスト）、buildspec_ci_fe_lint.yml（フロントの文法チェック） -
CDK のコード内に直接書かれた指示 …
pipeline-dev-stack.tsの中のbuildSpec: codebuild.BuildSpec.fromObject({...})。
デプロイ用のコマンド（docker build → push → ecs update）はこちら側に書かれています。
8-6. アカウントをまたぐ「通行許可証」(assume-role)
第7章で「Deployments と Workloads はアカウントが別」と言いました。
CI/CD は Deployments 側で動きますが、アプリ本体は Workloads 側にあります。
そこで pipeline-dev-stack.ts の中で、こういう処理をしています（簡略化・アカウント番号はダミー）：
# Workloads アカウントの「WorkloadDeployRole」になりすます（一時的な通行許可証を取得）
aws sts assume-role --role-arn arn:aws:iam::222233334444:role/WorkloadDeployRole ...
# その許可証を使って、Workloads 側の ECS を更新する
aws ecs update-service --cluster app-cluster --service backend-service --force-new-deployment
これが「別アカウントの家に入って作業する」ための仕組み（assume-role）です。
第9章 総まとめ ― コード1行が本番に届くまでの全工程
ここまでの知識を全部つないで、1つのストーリーにします。
開発者が「ボタンの色を変えた」修正をしたら、何が起きるか？
① 開発者が修正コードを CodeCommit の develop ブランチに push
│
▼
② （dev/stg では）PipelinePrCiStack のゲートが自動で検査
＝ lint（文法チェック）とテストを実行。失敗したら止まる（buildspec_ci_*.yml）
│ 検査OK・developにマージ
▼
③ PipelineDevStack のベルトコンベアが自動起動（IsAutoDeploy: true）
│
▼
[Source] CodeCommit から最新コードを取得
│
[ContainerBuild] Docker でアプリをビルド → ECR(倉庫)へ push
│ → WorkloadDeployRole になりすまして
│ ECS(店舗)を新イメージで入れ替え
│
[FunctionsUpdate] Lambda / StepFunctions / S3 を更新
│
[DbMigration] データベースの構造を最新化（alembic）
│
▼
④ Workloads アカウントの ECS 上で、新しいアプリが動き出す
│
▼
⑤ ユーザーが CloudFront(CDN) 経由でアクセス → 新しいボタンの色が見える！
そして、この ①〜⑤を動かす仕組み（CodeCommit / CodeBuild / Pipeline / ECR / ECS）自体も、
すべて pipeline-cdk の CDK コードで建てられている ── これが「CI/CD も CDK で定義されている」の意味です。
第10章 よく使うコマンド早見表
すべて該当の CDK フォルダ（infra-cdk か pipeline-cdk）の中で実行します。
# いま自分のコードと、AWS の現状との「違い」を確認する（安全。何も変えない）
npx cdk diff -c env=develop
# コードを CloudFormation テンプレートに翻訳するだけ（まだ作らない）
npx cdk synth -c env=develop
# 実際に AWS に建てる/更新する（本番反映。慎重に）
npx cdk deploy --all -c env=develop
# 特定のスタックだけ建てる（例：データベースだけ）
npx cdk deploy DatabaseStack -c env=develop
⚠️ 環境の指定
-c env=...を間違えると、違う環境に反映されます。 必ず確認してから実行してください。
（特にproductionへの deploy は要注意）
第11章 用語集（迷ったらここに戻る）
| 用語 | ひとことで言うと |
|---|---|
| AWS | コンピュータやDBを「借りられる」クラウドサービス |
| IaC | インフラ構成を「コード（レシピ）」で書く考え方 |
| CloudFormation | AWS 公式のレシピ形式（書くのは大変） |
| CDK | CloudFormation を TypeScript で書ける翻訳機。この資料の主役① |
| synth | コード → CloudFormation テンプレートに「翻訳」する |
| deploy | テンプレートを使って AWS に「実際に建てる」 |
| diff | 今の状態とコードの「差分」を見る |
| スタック | 関連する部品をまとめた管理単位（部屋割り） |
| 環境（dev/stg/prod） | 同じ構成の「場所」を用途別に複数用意したもの |
| CI/CD | コードを push すると検査〜配置まで自動化する仕組み。この資料の主役② |
| CodeCommit | コードの保管庫（Git） |
| CodeBuild | コードを組み立て・テストする作業員 |
| CodePipeline | 工程をつなぐベルトコンベア |
| ECR | 完成したアプリ（Dockerイメージ）の倉庫 |
| ECS / Fargate | アプリを実際に動かす場所 |
| VPC | 自分専用の仮想ネットワーク（土地） |
| RDS | データベース |
| assume-role | 別アカウントに入って作業するための「一時通行許可証」 |
| buildspec | CodeBuild への具体的な作業指示書 |
| alembic | データベースの表の構造を更新する道具 |
第12章 もっと詳しく知りたくなったら（実物の場所）
理解が進んだら、次のファイルを「答え合わせ」として開いてみてください。
| 知りたいこと | 見るファイル |
|---|---|
| インフラ全体の建てる順番 | infra-cdk/bin/infra-cdk.ts |
| 各部品の作り方（DB、ネットワークなど） |
infra-cdk/lib/*.ts（例：database-stack.ts） |
| 環境ごとの設定値 |
infra-cdk/config/develop.yml ほか |
| CI/CD パイプラインの建て方 | pipeline-cdk/bin/pipeline-cdk.ts |
| ベルトコンベアの中身（ステージ） | pipeline-cdk/lib/pipeline-dev-stack.ts |
| CI 検査の具体的コマンド | app/buildspec_ci_*.yml |
| CI/CD 環境ごとの設定値 |
pipeline-cdk/config/develop.yml ほか |
| 使い方（コマンド） | pipeline-cdk/README.md |
最後にもう一度、第0章のゴールを
「TypeScript で書いたコードを
cdk deployすると、AWS 上にサーバーやデータベースが自動で建ち（= infra-cdk）、
その後はコードを Git に push するだけで、アプリが自動で更新される（= pipeline-cdk が建てた CI/CD）」
この1文の意味が、今は最初より「絵」として浮かぶはずです。それが理解できた証拠です。
わからない単語が出てきたら、第11章の用語集に戻ってください。