こういう経験は、AWS CDKを使い始めたエンジニアがよくぶつかる壁です。
この記事では、AWS CDKの開発環境をnpmのバージョン管理から整える手順を解説します。
Amazon Linux 2023(AL2023)を想定環境として、マルチAZ構成設計に使えるCDKプロジェクトのセットアップまでをまとめます。
この記事のポイント
・ aws cdk npm のバージョン管理はnvmを使うと切り替えが簡単になる
・ CDK CLI は npm install -g aws-cdk でインストールし cdk --version で確認する
・ cdk init で始めたTypeScriptプロジェクトがマルチAZ設計の出発点になる
・ VPCのmaxAzsを指定することでマルチAZ配置を制御できる
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
AWS CDKでインフラをコードで管理するために必要なもの
AWS CDK(Cloud Development Kit)は、TypeScriptやPythonなどのプログラミング言語でAWSのインフラ構成を記述するツールです。CDKを使うとVPCの設計、サブネット、セキュリティグループなどを「コードとして管理」できます。
マルチAZ冗長設計のような複雑な構成も、繰り返し再現可能な形で定義できるのが特徴です。
CDKを動かすには以下の3つが必要です。
・Node.js:CDK CLIの実行基盤
・npm:CDK CLIと依存パッケージのインストールに使う
・AWS CLI:CDKからAWSへの接続に使う
特にNode.jsとnpmのバージョンは、CDKのバージョンと対応関係があります。
バージョンが合っていないと、インストールや実行時にエラーが出ることがあります。
Node.jsとnpmのバージョン管理(nvmを使う方法)
Node.jsのバージョン管理にはnvm(Node Version Manager)が便利です。複数のNode.jsバージョンを切り替えられるので、CDKのバージョンアップにも対応しやすくなります。
1. nvmのインストール
AL2023にはデフォルトでnvmが入っていません。以下の手順でインストールします。
# nvmのインストール(バージョンは最新のものを確認してから指定する) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # シェルの設定を再読み込みする source ~/.bashrc # インストール確認(出力例) nvm --version
0.39.7
2. CDKが要求するNode.jsバージョンの確認とインストール
AWS CDK v2は Node.js 18以上を推奨しています(2024年時点)。最新のLTSバージョンをインストールしておくのが安全です。
# 利用可能なNode.jsのLTSバージョン一覧を確認する nvm ls-remote --lts | tail -10 # 推奨バージョン(例: 20系のLTS)をインストールする nvm install 20 # インストールしたバージョンをデフォルトに設定する nvm alias default 20 # バージョン確認 node --version npm --version
v20.18.0 10.8.2
3. npmのバージョン更新
nvmでNode.jsをインストールするとnpmも一緒に入りますが、最新にしておくと依存解決の問題が減ります。# npmを最新バージョンに更新する npm install -g npm@latest # バージョン確認 npm --version
AWS CDK CLIのインストールと初期プロジェクト作成
Node.jsとnpmが整ったら、CDK CLIをインストールします。1. CDK CLIのインストールと動作確認
# CDK CLIをグローバルインストールする npm install -g aws-cdk # バージョン確認 cdk --version
2.168.0 (build xxxxxxx)
2. CDKアプリケーションの初期化
プロジェクト用のディレクトリを作成してから初期化します。TypeScriptで始めるのが、CDKの型補完を活かしやすい標準的な方法です。
# プロジェクトディレクトリを作成する mkdir my-multiaz-project cd my-multiaz-project # TypeScriptテンプレートでCDKプロジェクトを初期化する cdk init app --language typescript
my-multiaz-project/ ├── bin/ │ └── my-multiaz-project.ts # エントリーポイント ├── lib/ │ └── my-multiaz-project-stack.ts # スタック定義(ここにVPC等を書く) ├── package.json # npmの依存定義 ├── tsconfig.json └── cdk.json
3. VPC関連のライブラリをインストールする
CDKでVPCを操作するには aws-cdk-lib に含まれる ec2 モジュールを使います。初期化時にインストールされている場合がほとんどですが、確認しておきます。
# package.jsonの依存を確認する cat package.json | grep aws-cdk-lib # 未インストールの場合はインストールする npm install aws-cdk-lib constructs
Amazon LinuxでAWSを始めるための環境構築も合わせて参考にしてください。
マルチAZ構成をCDKで定義する基本パターン
開発環境が整ったら、マルチAZ構成の定義に進みます。CDKのVPCコンストラクトは、マルチAZ配置をシンプルなコードで記述できます。
1. VPCとマルチAZサブネットの設計方針
マルチAZ冗長設計の基本は「2つ以上のAZにサブネットを分散する」ことです。CDKではVPCコンストラクトの `maxAzs` プロパティでAZ数を指定します。
典型的な設計パターンは以下のとおりです。
・パブリックサブネット:ALBやNATゲートウェイを配置するAZ×2
・プライベートサブネット:EC2やRDSを配置するAZ×2
・AZ障害時の継続性:一方のAZが落ちても他方で処理を継続できる構成
2. CDKスタックにマルチAZ VPCを定義する
lib/my-multiaz-project-stack.ts を編集してVPCを定義します。import * as cdk from 'aws-cdk-lib'; import * as ec2 from 'aws-cdk-lib/aws-ec2'; import { Construct } from 'constructs'; export class MyMultiazProjectStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // マルチAZ VPCを定義する(2AZにパブリック・プライベートサブネットを配置) const vpc = new ec2.Vpc(this, 'MultiAzVpc', { maxAzs: 2, // 使用するAZ数 natGateways: 1, // NATゲートウェイの数(コスト節約のため1台) subnetConfiguration: [ { cidrMask: 24, name: 'Public', subnetType: ec2.SubnetType.PUBLIC, }, { cidrMask: 24, name: 'Private', subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS, }, ], }); } }
# TypeScriptをコンパイルする npm run build # CDKの構成をCloudFormationテンプレートとして確認する cdk synth
実際にデプロイする前に、まず構成を目で確認してみてください。
バージョン不整合のエラーと対処法
CDKとnpmの組み合わせで起きやすいエラーをまとめます。| エラー内容 | 原因と対処 |
|---|---|
| cdk: command not found | CDK CLIのインストール未完了。npm install -g aws-cdk を実行する |
| Unsupported engine: node | Node.jsのバージョンが古い。nvm install 20 で更新する |
| EACCES permission denied | npmのグローバルインストール権限不足。nvmを使っていれば sudo は不要 |
| cdk deploy: Unable to resolve AWS account | AWS CLIの認証情報が未設定。aws configure を実行して設定する |
| This CDK CLI is not compatible with the CDK library used | CLIとライブラリのバージョン差異。npm update aws-cdk aws-cdk-lib で揃える |
「This CDK CLI is not compatible」のエラーは、CDK CLIとaws-cdk-libのバージョンが大きくずれたときに出ます。
グローバルのCLIとプロジェクトのライブラリを同じバージョン系列に保つことが重要です。
本記事のまとめ
AWS CDKとnpmのバージョン管理から、マルチAZ構成設計を始めるまでの流れをまとめます。| 手順 | コマンド・設定 |
|---|---|
| nvmのインストール | curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash |
| Node.jsのインストール | nvm install 20 && nvm alias default 20 |
| CDK CLIのインストール | npm install -g aws-cdk |
| プロジェクト初期化 | cdk init app --language typescript |
| VPC定義(マルチAZ) | new ec2.Vpc(..., { maxAzs: 2, ... }) |
| 構成確認 | npm run build && cdk synth |
AWS CDKはnpmとNode.jsのバージョン管理を最初にしっかり整えることで、後のトラブルを大きく減らせます。
nvmで環境を切り替えられる状態にしておけば、CDKのバージョンアップにも対応しやすくなります。
マルチAZ構成の設計をさらに深めるには、より詳しい冗長設計の知識が必要です。
Amazon LinuxでAWSを学ぶためのメルマガでは、LinuxサーバーとAWSの実務的な使い方をまとめています。
無料のLinuxサーバー構築入門マニュアル(図解60P)をプレゼントしています。
>>無料マニュアルのダウンロードはこちら
3,100名以上が実践した「型」を無料で公開中
プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。
姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら
- 次のページへ:AWS CDKのversionをプロジェクト間で統一してVPC設計を再利用する方法|固定化の手順
- 前のページへ:aws-cdk-libのL2 ConstructでAWSマルチAZ VPC冗長設計を実装する手順|Stackの構成方法
- この記事の属するカテゴリ:AWS(Amazon Linux)へ戻る

無料メルマガで学習を続ける
Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。
登録無料・いつでも解除できます