AWS CDKカスタムCLI:開発体験をどう改善するか?

2025.12.11
AWS CDKカスタムCLI:開発体験をどう改善するか?
この記事をシェアする

はじめに

AWS CDKでインフラを管理している皆さん、こんな課題を感じたことはないでしょうか?

  • 複数のスタックを順序通りにデプロイするのが煩雑
  • AWS SSOの認証切れに気づかずコマンド実行して失敗してしまう
  • 環境やスタックの指定ミスによる本番環境への誤デプロイのリスク
  • ドリフト検出やコードチェックなど、よく使うコマンドの実行が面倒

標準のCDKコマンドだけでは、これらの課題を解決するのは難しいのが現状です。

そこで本記事では、Bunとインタラクティブなプロンプトを活用したカスタムCLIを実装し、これらの課題をどう解決したかを解説します。実装方法から実際の使い方まで、順を追ってご紹介していきます。

前提条件

本記事で紹介するカスタムCLIを実装・利用するには、以下の環境が必要です。

必須要件

AWS環境

  • AWS CLI: v2.x 以降
  • AWS SSO による認証設定が完了していること
  • AWS CDK: 2.x 以降(本記事では 2.1031.1 を使用)

ランタイム・開発環境

  • mise: ランタイムバージョン管理ツール(推奨)
  • TypeScript: v5.x 以降(本記事では v5.4.5 を使用)

主要パッケージのバージョン

  • aws-cdk-lib: 2.222.0
  • aws-cdk (CLI): 2.1031.2
  • @aws-sdk/client-cloudformation: 3.911.0
  • @aws-sdk/client-sts: 3.911.0
  • @inquirer/prompts: 7.9.0
  • @biomejs/biome: 1.9.4
  • cspell: 8.19.0

miseとは

miseは、複数のランタイムバージョンを管理できるツールです。プロジェクトごとに異なるバージョンのBunやNode.jsを自動的に切り替えることができ、チーム開発での環境統一に役立ちます。

# miseのインストール(macOS)
brew install mise

# シェル設定の追加(zsh)
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

必要なnpmパッケージ

以下のパッケージを使用します。バージョンは参考値です。

{
  "devDependencies": {
    "@aws-sdk/client-cloudformation": "^3.911.0",
    "@aws-sdk/client-sts": "^3.911.0",
    "@aws-sdk/credential-providers": "^3.911.0",
    "@biomejs/biome": "^1.9.4",
    "@inquirer/prompts": "^7.9.0",
    "@types/node": "^24.10.1",
    "aws-cdk": "^2.1031.2",
    "bun-types": "^1.3.2",
    "cspell": "^8.19.0",
    "ts-node": "^10.9.2",
    "typescript": "~5.4.5"
  },
  "dependencies": {
    "aws-cdk-lib": "2.222.0",
    "constructs": "^10.3.0"
  }
}

主要パッケージの役割

  • @inquirer/prompts: インタラクティブなプロンプトUI
  • @aws-sdk/client-sts: AWS SSO認証の確認
  • @aws-sdk/client-cloudformation: ドリフト検出機能
  • @biomejs/biome: コードフォーマット・リント
  • cspell: スペルチェック
  • aws-cdk-lib: AWS CDK本体

AWS SSO設定について

本CLIはAWS SSOによる認証を前提としています。事前に以下のコマンドでSSO設定を完了させてください。

# SSO設定の初期化
aws configure sso --profile your-profile-name

プロンプトに従い、以下を入力:

  • SSO session name: 任意の名前(例: your-session)
  • SSO start URL: https://your-domain.awsapps.com/start(組織の管理者に確認)
  • SSO region: ap-northeast-1
  • SSO registration scopes: sso:account:access(デフォルト、EnterでOK)
  • CLI default client Region: ap-northeast-1
  • CLI default output format: json
  • プロファイル名: 開発環境は dev-your-company、本番環境は prod-your-company

mise を使ったセットアップ

サンプルプロジェクトでは、mise を使用してBunとNode.jsのバージョンを管理しています。

# プロジェクトディレクトリに移動
cd aws-cdk-custom-cli

# mise.toml ファイルを信頼(初回のみ必要)
mise trust

# mise が mise.toml を読み込み、必要なツールをインストール
# 初回は確認メッセージが表示されます
# "Would you like to install these tools? [y/n]" → y を入力

# インストール確認
mise current
# bun    1.2.21  ~/path/to/aws-cdk-custom-cli/mise.toml
# node   22.14.0 ~/path/to/aws-cdk-custom-cli/mise.toml

# 依存関係のインストール
bun install

セキュリティ: mise trust コマンドは、プロジェクトの mise.toml ファイルを安全に使用するために必要です。これにより、信頼していないプロジェクトで悪意のあるコードが実行されるのを防ぎます。

mise.toml の例

[tools]
bun = "1.2.21"
node = "22.14.0"

[env]
_.path = ["./node_modules/.bin"]

サンプルコード

本記事で紹介するカスタムCLIの完全なサンプルコードは、以下のGitHubリポジトリで公開しています:

GitHub Repository: https://github.com/cb-y-sato/blog-repo

リポジトリ内の articles/aws-cdk-custom-cli/ ディレクトリに、すべてのコードとドキュメントが含まれています。

次の章からソースコードの説明や実装によるメリット、デメリットなどを記載していますが、手っ取り早く動きを確認したい方はgit cloneしてREADMEの手順を実行してみてください。

サンプルに含まれる内容

  • 完全なCLI実装コード: インタラクティブなプロンプトとAWS連携
  • 2つのサンプルスタック: 実際にデプロイ可能なスタック
  • 設定ファイル: mise.toml、biome.json、cspell.json等
  • 詳細なドキュメント:

サンプルスタックの特徴

Sample Stack 1 – EventBridge ルール

  • 毎日日本時間 9:00(UTC 0:00)に実行されるスケジュールルール
  • ターゲットは未設定(用途に応じてLambdaやSNS等を追加可能)
  • CloudFormation Outputsでルール名とARNを出力

Sample Stack 2 – Lambda 関数

  • Node.js 20.x ランタイムのシンプルなLambda関数
  • インラインコードでデプロイが簡単
  • CloudFormation Outputsで関数名とARNを出力

カスタムCLIの概要

今回実装したCLIは、bun run cli というシンプルなコマンドで起動し、インタラクティブな質問形式で以下の機能を提供しています:

主な機能

  1. デプロイモード – AWS CDKスタックのデプロイ・管理
  2. ドリフト検出モード – CloudFormationドリフトの確認
  3. 開発ツールモード – コードチェック・フォーマット・ビルド

カスタムCLIのメリット

1. ヒューマンエラーの防止

インタラクティブなプロンプトにより、環境やスタックを選択肢から選ぶだけで済むようになります。コマンドライン引数を手動で入力する必要がないため、指定ミスや本番環境への誤デプロイといった重大な事故を防ぐことができます。

これは特に、複数の環境を管理している場合や、チーム開発において重要なメリットとなります。

# 従来の方法:引数を手動で指定する必要がある
cdk deploy MyApp-Network-prod --profile prod-company --require-approval never

# カスタムCLI:対話形式で選択
bun run cli
# 🎯 実行するモードを選択してください: → 🚀 デプロイ - AWS CDKスタックのデプロイ・管理
# 🌏 デプロイ環境を選択してください: → 本番環境 (prod)
# ⚙️ AWSプロファイルを選択してください: → prod-company
# 📦 デプロイするスタックを選択してください: → Network - VPC、サブネット、セキュリティグループ

2. AWS SSO認証の自動化

AWS SSOの認証状態を自動でチェックし、期限切れの場合は自動的にログイン処理を実行します。これにより、「認証が切れていることに気づかずコマンド実行して失敗する」という事態を防ぐことができます。

// 認証状態を確認し、必要に応じて自動ログイン
await awsAuth.ssoLogin();

開発中は認証の有効期限が切れることも多いため、この自動化により作業の中断を最小限に抑えることができるという利点があります。

3. 複雑な操作の簡素化

ドリフト検出など、通常は複数のAWS CLIコマンドを組み合わせる必要がある操作を、1つの選択肢で実行することが可能になります。これにより、高度な機能をより手軽に利用できるようになります。

4. 実行前の確認と安全性の向上

すべての操作において、実行前に設定内容のサマリーが表示され、確認を求められる仕組みになっています。特にdestroyコマンドでは、”DELETE”という文字列の入力を要求することで、誤った削除を二重に防ぐ設計となっています。

📊 設定サマリー:
  環境: prod
  AWSプロファイル: prod-company
  スタック: MyApp-Database-prod
  CDKコマンド: destroy

⚠️  警告: スタックを削除すると、すべてのリソースが削除されます。
この操作は取り消せません。
? 削除を確認するには "DELETE" と入力してください:

5. 高速な起動と実行

Bunを使用することで、Node.jsと比較して高速に起動・実行することができます。頻繁に使用するツールだからこそ、この起動速度の向上は開発体験の改善に大きく貢献します。

カスタムCLIのデメリット

便利な一方で、いくつかのデメリットも存在します。導入を検討される際は、以下の点を考慮することが重要です。

1. CIパイプラインでの使用には不向き

インタラクティブなプロンプトを前提としているため、CI/CDパイプラインでは使用することができません。CI環境では従来通りCDKコマンドを直接使用する必要があります。

ただし、これは設計上の意図的な制約であり、ローカル開発環境での手動操作に特化することで、より使いやすいUIを実現しています。

# CI/CDではこのように直接CDKコマンドを使用
- name: Deploy to production
  run: cdk deploy --all --require-approval never

2. Bunへの依存

Bunランタイムが必要なため、開発環境にBunのインストールが必須となります。ただし、Bunは高速で軽量なランタイムであり、インストールの負担は小さいと言えます。

3. 学習コスト

チームメンバーが標準のCDKコマンドに慣れている場合、新しいCLIの使い方を覚える必要があります。ただし、インタラクティブなUIにより直感的に操作できるため、実際の学習コストは低く抑えられています。

4. メンテナンスコスト

スタックの追加や設定の変更に応じて、CLIのコードも更新する必要があります。これは、カスタムツールを導入する際の一般的なトレードオフと言えるでしょう。

実装解説

プロジェクト構成

.
├── mise.toml                # mise設定(Bun/Node.jsバージョン管理)
├── package.json             # 依存関係
├── tsconfig.json            # TypeScript設定
├── cdk.json                 # CDK設定
├── README.md                # 詳細ドキュメント
├── INSTALL.md               # mise詳細ガイド
├── QUICKSTART.md            # クイックスタート
├── bin/
│   └── app.ts              # CDKアプリエントリーポイント
├── lib/
│   ├── config.ts           # 環境設定
│   ├── sample-stack1.ts    # Sample Stack 1(EventBridge)
│   └── sample-stack2.ts    # Sample Stack 2(Lambda)
└── scripts/cli/
    ├── index.ts            # CLIメインエントリーポイント
    ├── aws/
    │   └── auth.ts         # AWS SSO認証処理
    ├── config/
    │   ├── mode.ts         # モード定義(deploy/drift/dev)
    │   ├── stage.ts        # 環境定義(dev/prod)
    │   ├── stack.ts        # スタック定義
    │   ├── cdk-command.ts  # CDKコマンド定義
    │   └── dev-command.ts  # 開発ツールコマンド定義
    └── utils/
        ├── config.ts       # 設定取得処理
        └── async.ts        # 非同期ユーティリティ

0. mise.toml によるバージョン管理

プロジェクトのルートに mise.toml を配置します。これにより、チーム全体で同じバージョンのBunとNode.jsを使用できます。

[tools]
bun = "1.2.21"
node = "22.14.0"

[env]
_.path = ["./node_modules/.bin"]

プロジェクトディレクトリに入ると、mise が自動的にこれらのツールをインストール・切り替えします。

1. package.jsonでのスクリプト定義

次に、package.jsonにCLIを起動するためのスクリプトを定義します。

{
  "scripts": {
    "cli": "bun run scripts/cli/index.ts",
    "build": "tsc",
    "lint": "biome lint .",
    "format": "biome format --write .",
    "check": "biome check .",
    "spell-check": "cspell \"**/*.{ts,md,json}\""
  }
}

2. モード定義

3つのモード(デプロイ、ドリフト検出、開発ツール)を定義し、ユーザーが最初に選択できるようにします。これにより、目的に応じた機能に素早くアクセスすることが可能になります。

// config/mode.ts
export const Mode = {
  deploy: 'deploy',
  drift: 'drift',
  dev: 'dev',
} as const;

export type Mode = (typeof Mode)[keyof typeof Mode];

export const modeLabels: Record<Mode, string> = {
  [Mode.deploy]: '🚀 デプロイ - AWS CDKスタックのデプロイ・管理',
  [Mode.drift]: '📡 ドリフト検出 - CloudFormationドリフトの確認',
  [Mode.dev]: '🛠️ 開発ツール - コードチェック・フォーマット・ビルド',
};

3. スタック定義

管理するすべてのスタックを定義し、依存関係を適切に管理する仕組みを実装します。これにより、複数スタックを正しい順序でデプロイすることが可能になります。

// config/stack.ts
export const StackType = {
  artifacts: 'artifacts',
  network: 'network',
  storage: 'storage',
  database: 'database',
  compute: 'compute',
  cicd: 'cicd',
  bastion: 'bastion',
  edge: 'edge',
  observability: 'observability',
  scheduler: 'scheduler',
  main: 'main',  // 複数スタックのグループ
  all: 'all',    // すべてのスタック
} as const;

export const stackLabels: Record<StackType, string> = {
  [StackType.artifacts]: '事前デプロイ(ECRなどの事前リソース)',
  [StackType.network]: 'Network - VPC、サブネット、セキュリティグループ',
  [StackType.storage]: 'Storage - S3バケット',
  [StackType.database]: 'Database - RDS/Aurora',
  [StackType.compute]: 'Compute - ECS、ALB',
  // ... 他のスタック
};

// スタック名を生成する関数
export function getStackName(stack: StackType, stage: string): string {
  const stackNameCapitalized = stack.charAt(0).toUpperCase() + stack.slice(1);
  return `MyApp-${stackNameCapitalized}-${stage}`;
}

4. AWS SSO認証処理

AWS SSOの認証状態を自動的にチェックし、必要に応じてログイン処理を実行する仕組みを実装します。これが、認証切れによる実行失敗を防ぐ重要な機能となります。

// aws/auth.ts
import { GetCallerIdentityCommand, STSClient } from '@aws-sdk/client-sts';
import { fromSSO } from '@aws-sdk/credential-providers';
import { spawn } from 'bun';

export class AwsAuth {
  readonly region: string;
  readonly profile: string;

  constructor({ region, profile }: { region: string; profile: string }) {
    this.region = region;
    this.profile = profile;
  }

  /**
   * 認証状態をチェックする
   */
  async checkAuthenticationState(): Promise<boolean> {
    try {
      const stsClient = new STSClient({
        region: this.region,
        credentials: fromSSO({ profile: this.profile }),
      });

      await stsClient.send(new GetCallerIdentityCommand({}));
      return true;
    } catch {
      return false;
    }
  }

  /**
   * SSO ログインを実行する
   */
  async ssoLogin(): Promise<void> {
    const isAuthenticated = await this.checkAuthenticationState();
    if (isAuthenticated) {
      return;
    }

    console.log('🔐 AWS SSOにログイン中...');
    const proc = spawn(['aws', 'sso', 'login', '--profile', this.profile], {
      stdio: ['inherit', 'inherit', 'inherit'],
    });
    await proc.exited;

    if (proc.exitCode !== 0) {
      console.error('❌ AWS SSOログインに失敗しました');
      process.exit(1);
    }
    console.log('✅ AWS SSOログインが完了しました');
  }

  /**
   * AWS プロファイル一覧を取得(フィルタリング可能)
   */
  static async getAwsProfiles({
    nameFilter,
  }: {
    nameFilter?: string[];
  }): Promise<string[]> {
    const proc = spawn(['aws', 'configure', 'list-profiles'], {
      stdio: ['inherit', 'pipe', 'inherit'],
    });

    await proc.exited;
    const output = await new Response(proc.stdout).text();
    
    return output
      .trim()
      .split('\n')
      .filter((profile) =>
        nameFilter == null 
          ? true 
          : nameFilter.every((filter) => profile.includes(filter))
      );
  }
}

5. メインロジック

@inquirer/promptsを使用したインタラクティブなプロンプトにより、ユーザー入力を受け取り、適切な処理を実行する仕組みを実装します。この部分が、使いやすいUIを実現する核となる実装です。

// index.ts
import { select, confirm, input } from '@inquirer/prompts';
import { spawn } from 'bun';

const main = async (): Promise<void> => {
  // 1. モード選択
  const mode = await select<Mode>({
    message: '🎯 実行するモードを選択してください:',
    choices: ModeValues.map((m) => ({
      name: modeLabels[m],
      value: m,
    })),
  });

  // 2. 開発ツールモードの場合
  if (mode === Mode.dev) {
    const devCommand = await select<DevCommand>({
      message: '🛠️ 開発ツールを選択してください:',
      choices: DevCommandValues.map((cmd) => ({
        name: devCommandLabels[cmd],
        value: cmd,
      })),
    });

    // npmスクリプトを実行
    const npmScript = devCommandNpmScripts[devCommand];
    const proc = spawn(['npm', 'run', npmScript], {
      stdio: ['inherit', 'inherit', 'inherit'],
    });
    await proc.exited;
    return;
  }

  // 3. ドリフト検出モードの場合
  if (mode === Mode.drift) {
    const config = await getDriftConfig();
    const awsAuth = new AwsAuth({
      region: 'ap-northeast-1',
      profile: config.awsProfile,
    });

    await awsAuth.ssoLogin();

    // ドリフト検出を実行
    await runDriftCheck({
      profile: config.awsProfile,
      stage: config.stage,
      stack: config.stack,
    });
    return;
  }

  // 4. デプロイモードの場合
  const config = await getDeployConfig();
  const awsAuth = new AwsAuth({
    region: 'ap-northeast-1',
    profile: config.awsProfile,
  });

  await awsAuth.ssoLogin();

  // CDKコマンドを構築
  const commands = ['cdk', config.cdkCommand];
  commands.push('-c', `env=${config.stage}`);
  commands.push('--profile', config.awsProfile);
  
  // スタックを追加
  const stackTargets = getStackTargets(config.stack, config.stage);
  if (stackTargets.useAll) {
    commands.push('--all');
  } else {
    commands.push(...stackTargets.stacks);
  }

  // デプロイオプションを追加
  if (config.cdkCommand === 'deploy') {
    if (config.requireApproval) {
      commands.push('--require-approval', 'any-change');
    } else {
      commands.push('--require-approval', 'never');
    }

    if (config.hotswap) {
      commands.push('--hotswap');
    }
  }

  // destroyの場合は追加確認
  if (config.cdkCommand === 'destroy') {
    console.log('\n⚠️  警告: スタックを削除すると、すべてのリソースが削除されます。');
    console.log('この操作は取り消せません。');

    const confirmText = await input({
      message: '削除を確認するには "DELETE" と入力してください:',
    });

    if (confirmText !== 'DELETE') {
      console.log('❌ 削除がキャンセルされました');
      return;
    }
  }

  // 設定サマリーを表示
  console.log('\n📊 設定サマリー:');
  console.log(`  実行コマンド: ${commands.join(' ')}`);
  console.log(`  環境: ${config.stage}`);
  console.log(`  AWSプロファイル: ${config.awsProfile}`);
  console.log(`  スタック: ${stackTargets.summaryName}`);

  // 実行確認
  const shouldProceed = await confirm({
    message: `🚀 ${config.cdkCommand}を実行しますか?`,
    default: config.cdkCommand !== 'destroy',
  });

  if (!shouldProceed) {
    console.log('ユーザーによって実行がキャンセルされました');
    return;
  }

  // CDKコマンドを実行
  const proc = spawn(commands, {
    env: {
      ...process.env,
      AWS_PROFILE: config.awsProfile,
      AWS_REGION: 'ap-northeast-1',
    },
    stdio: ['inherit', 'inherit', 'inherit'],
  });
  await proc.exited;

  if (proc.exitCode !== 0) {
    console.error(`❌ ${config.cdkCommand}に失敗しました`);
    process.exit(1);
  }

  console.log(`\n🎉 ${config.cdkCommand}が正常に完了しました`);
};

if (import.meta.main) {
  await main();
}

6. ドリフト検出の実装

CloudFormationのドリフト検出APIを使用して、スタックの実際の状態とテンプレートの差分を確認する機能を実装します。通常は複数のAWS CLIコマンドを組み合わせる必要がある操作を、シンプルなインターフェースで提供しています。

const runStackDriftDetection = async (params: {
  client: CloudFormationClient;
  stackName: string;
}): Promise<void> => {
  const { client, stackName } = params;

  console.log(`\n🔍 スタック ${stackName} のドリフト検出を開始します...`);

  // ドリフト検出を開始
  const detectRes = await client.send(
    new DetectStackDriftCommand({ StackName: stackName })
  );

  // 検出完了まで待機
  let statusRes = await client.send(
    new DescribeStackDriftDetectionStatusCommand({
      StackDriftDetectionId: detectRes.StackDriftDetectionId,
    })
  );

  while (statusRes.DetectionStatus === 'DETECTION_IN_PROGRESS') {
    await sleep(3000);
    statusRes = await client.send(
      new DescribeStackDriftDetectionStatusCommand({
        StackDriftDetectionId: detectRes.StackDriftDetectionId,
      })
    );
  }

  const status = statusRes.StackDriftStatus ?? 'UNKNOWN';
  console.log(`${stackName}: ${status}`);

  // ドリフトが検出された場合、詳細を表示
  if (status === 'DRIFTED') {
    await printStackResourceDrifts(client, stackName);
  }
};

const printStackResourceDrifts = async (
  client: CloudFormationClient,
  stackName: string
): Promise<void> => {
  console.log('  詳細(リソース単位のドリフト):');

  const res = await client.send(
    new DescribeStackResourceDriftsCommand({ StackName: stackName })
  );

  const drifts = (res.StackResourceDrifts ?? []).filter(
    (resource) => resource.StackResourceDriftStatus !== 'IN_SYNC'
  );

  for (const drift of drifts) {
    console.log(
      `  - ${drift.ResourceType} ${drift.LogicalResourceId}: ${drift.StackResourceDriftStatus}`
    );

    // プロパティの差分を表示(最大3件)
    const propDiffs = drift.PropertyDifferences ?? [];
    for (const diff of propDiffs.slice(0, 3)) {
      console.log(
        `      ${diff.PropertyPath}: expected=${diff.ExpectedValue} actual=${diff.ActualValue}`
      );
    }
  }
};

使い方

基本的な使い方

# CLIを起動
bun run cli

# または、開発環境で頻繁に使う場合はエイリアスを設定
# ~/.zshrc または ~/.bashrc に追加
alias infra="cd /path/to/your/project && bun run cli"

# エイリアスを使った実行
infra

ユースケース1: 開発環境へのデプロイ

$ bun run cli

# 1. モード選択
? 🎯 実行するモードを選択してください: 
  ❯ 🚀 デプロイ - AWS CDKスタックのデプロイ・管理
    📡 ドリフト検出 - CloudFormationドリフトの確認
    🛠️ 開発ツール - コードチェック・フォーマット・ビルド

# 2. 環境選択
? 🌏 デプロイ環境を選択してください:
  ❯ 開発環境 (dev)
    本番環境 (prod)

# 3. AWSプロファイル選択
? ⚙️ AWSプロファイルを選択してください:
  ❯ dev-company

# 4. スタック選択
? 📦 デプロイするスタックを選択してください:
  ❯ Sample Stack 1 - EventBridge ルール
    Sample Stack 2 - Lambda 関数

# 5. CDKコマンド選択
? 🔧 CDK コマンドを選択してください:
  ❯ deploy - スタックをデプロイ
    diff - 差分を確認
    synth - CloudFormationテンプレートを生成
    destroy - スタックを削除

# 6. オプション選択
? 🔒 変更の承認を必須にしますか?(--require-approval) (Y/n)
? ⚡ Hotswapモードを使用しますか?(Lambda/ECSの高速デプロイ、開発環境のみ推奨) (y/N)

# 7. 設定サマリー表示と確認
📊 設定サマリー:
  実行コマンド: cdk deploy -c env=dev --profile dev-company CustomCliSample1-Dev --require-approval any-change
  環境: dev
  AWSプロファイル: dev-company
  スタック: CustomCliSample1-Dev
  CDKコマンド: deploy
  承認要求: あり
  Hotswapモード: OFF

? 🚀 deployを実行しますか? (Y/n)

# AWS SSOの自動ログイン(必要な場合)
🔐 AWS SSOにログイン中...
✅ AWS SSOログインが完了しました

# デプロイ実行
# ... CDKのデプロイ出力 ...

🎉 deployが正常に完了しました

ユースケース2: 本番環境のドリフト検出

$ bun run cli drift

# または、CLIから選択
$ bun run cli
? 🎯 実行するモードを選択してください: 
  ❯ 📡 ドリフト検出 - CloudFormationドリフトの確認

? 🌏 ドリフト検出対象の環境を選択してください:
  ❯ 本番環境 (prod)

? ⚙️ AWSプロファイルを選択してください:
  ❯ prod-company

? 📦 ドリフト検出対象のスタックを選択してください:
  ❯ Sample Stack 1 - EventBridge ルール
    Sample Stack 2 - Lambda 関数

📊 設定サマリー(ドリフト検出):
  実行モード: drift
  環境: prod
  AWSプロファイル: prod-company
  ターゲットスタック: CustomCliSample1-Prod

? 🚀 CloudFormation ドリフト検出を実行しますか? (Y/n)

🔐 AWS SSOにログイン中...
✅ AWS SSOログインが完了しました

📡 CloudFormation ドリフト検出を開始します...

🔍 スタック CustomCliSample1-Prod のドリフト検出を開始します...
CustomCliSample1-Prod: IN_SYNC

🎉 ドリフト検出が完了しました

ユースケース3: コードフォーマット

$ bun run cli

? 🎯 実行するモードを選択してください: 
  ❯ 🛠️ 開発ツール - コードチェック・フォーマット・ビルド

? 🛠️ 開発ツールを選択してください:
    spell-check - スペルチェックを実行
    biome check - コードチェック(修正なし)
    biome check --write - コードチェック(自動修正)
    biome lint - リントチェック(修正なし)
    biome lint --write - リントチェック(自動修正)
  ❯ biome format --write - コードフォーマット
    build - TypeScriptビルド

📊 実行コマンド:
  npm run format

? 🚀 biome format --write - コードフォーマットを実行しますか? (Y/n)

# ... Biomeのフォーマット出力 ...

🎉 biome format --write - コードフォーマットが正常に完了しました

ユースケース4: 本番環境へのスタック削除(慎重な操作)

$ bun run cli

? 🎯 実行するモードを選択してください: 
  ❯ 🚀 デプロイ - AWS CDKスタックのデプロイ・管理

? 🌏 デプロイ環境を選択してください:
  ❯ 本番環境 (prod)

? ⚙️ AWSプロファイルを選択してください:
  ❯ prod-company

? 📦 デプロイするスタックを選択してください:
  ❯ Sample Stack 2 - Lambda 関数

? 🔧 CDK コマンドを選択してください:
  ❯ destroy - スタックを削除

📊 設定サマリー:
  実行コマンド: cdk destroy --profile prod-company CustomCliSample2-Prod
  環境: prod
  AWSプロファイル: prod-company
  スタック: CustomCliSample2-Prod
  CDKコマンド: destroy

⚠️  警告: スタックを削除すると、すべてのリソースが削除されます。
この操作は取り消せません。

? 削除を確認するには "DELETE" と入力してください: DELETE

? 🚀 destroyを実行しますか? (y/N) y

# ... CDKの削除出力 ...

🎉 destroyが正常に完了しました

応用例

1. サブコマンドの追加

ドリフト検出専用のサブコマンドを追加することで、モード選択をスキップできます。

# ドリフト検出モードに直接遷移
bun run cli drift

実装は以下のようにコマンドライン引数を解析します:

const parseCliArgs = (): CliArgs => {
  const args = process.argv.slice(2);
  let subcommand: 'drift' | undefined;

  for (const arg of args) {
    if (arg === 'drift') {
      subcommand = 'drift';
    }
  }

  return { subcommand };
};

const main = async (): Promise<void> => {
  const { subcommand } = parseCliArgs();

  const mode = subcommand === 'drift'
    ? Mode.drift
    : await select<Mode>({...});
  
  // ...
};

2. 環境変数によるデフォルト値の設定

頻繁に使う設定を環境変数で指定できるようにします。

# ~/.zshrc または ~/.bashrc
export CDK_CLI_DEFAULT_ENV=dev
export CDK_CLI_DEFAULT_PROFILE=dev-company

bun run cli  # dev環境とdev-companyプロファイルがデフォルトで選択される
const getDeployConfig = async (): Promise<DeployConfig> => {
  const stage = await select<Stage>({
    message: '🌏 デプロイ環境を選択してください:',
    choices: StageValues.map((stage) => ({
      name: stageLabels[stage],
      value: stage,
    })),
    default: process.env.CDK_CLI_DEFAULT_ENV || undefined,
  });
  // ...
};

3. デプロイ履歴の記録

デプロイ実行時に履歴をJSONファイルに記録します。

const recordDeployment = (config: DeployConfig) => {
  const history = {
    timestamp: new Date().toISOString(),
    environment: config.stage,
    profile: config.awsProfile,
    stack: config.stack,
    command: config.cdkCommand,
  };

  const historyFile = '.cdk-deploy-history.json';
  const existingHistory = fs.existsSync(historyFile)
    ? JSON.parse(fs.readFileSync(historyFile, 'utf-8'))
    : [];

  existingHistory.push(history);
  fs.writeFileSync(historyFile, JSON.stringify(existingHistory, null, 2));
};

まとめと今後の展望

本記事では、AWS CDKプロジェクト向けのカスタムCLIを実装し、開発体験をどのように改善できるかを解説してきました。

カスタムCLIの導入により、以下のような効果が得られます:

  1. ヒューマンエラーの防止 – インタラクティブな選択式UIによる誤操作の削減
  2. 認証の自動化 – AWS SSO認証の自動チェックとログイン
  3. 複雑な操作の簡素化 – ドリフト検出などの高度な機能を簡単に実行
  4. 安全性の向上 – 実行前の確認とdestroyコマンドの二重確認
  5. 開発体験の向上 – Bunによる高速な起動と実行

一方で、CIパイプラインでは使用できない点や、Bunへの依存などのデメリットも存在します。これらを考慮すると、ローカル開発環境での手動操作に特化したツールとして位置づけ、CI/CDでは従来のCDKコマンドを使用する、というハイブリッドな運用が推奨されます。

今後の発展可能性

このカスタムCLIは、さらなる機能拡張の余地があります:

  • コスト見積もり機能の統合 – デプロイ前にコスト試算を実行
  • デプロイ履歴の可視化 – 過去のデプロイ履歴をダッシュボード形式で表示
  • ロールバック機能 – 問題発生時の迅速な切り戻し
  • チーム通知の統合 – Slack等への通知機能

AWS CDKを使ったインフラ管理で、複数環境・複数スタックの運用に課題を感じている方は、ぜひカスタムCLIの導入を検討してみてください。開発体験の改善が、チーム全体の生産性向上につながることでしょう。

参考リンク

この記事をシェアする
著者:さとゆう
CloudFormationによるインフラ構築の効率化が好きなAWSエンジニア。最近はAIサービスのプロンプトエンジニアリングを勉強中。