cdk-with-localstack

CDKをLocalStackにデプロイする検証用リポジトリ。

GitHub Actions ワークフロー

本リポジトリでは2つのデプロイパターンを提供しています：

1. deploy-with-setup.yml (推奨)

アーキテクチャ: setup-localstack GitHub Actionを利用した統合アプローチ

特徴:

• LocalStackの起動・停止を自動管理
• awslocal CLIの自動インストール
• ヘルスチェックや手動クリーンアップ不要
• CI/CD環境での実行を想定した設計

推奨理由: LocalStack公式のアクションにより、セットアップが簡素化され、メンテナンス性が向上します。

2. deploy-with-docker.yml

アーキテクチャ: Docker Composeを利用した従来型アプローチ

特徴:

• docker-compose.yml を使用して手動でLocalStackを起動
• ヘルスチェックとクリーンアップ（docker compose down）を明示的に実行
• ローカル開発環境との一貫性を重視

適用場面: Docker Composeの動作を細かく制御したい場合や、ローカル環境と同じ構成をCI/CDで再現したい場合に有用です。

クイックスタート（ローカル開発）

# 依存関係のインストールとビルド
npm install
npm run build

# LocalStack起動
docker compose up -d

# CDKデプロイ
npx cdklocal deploy --require-approval never

# LocalStack停止
docker compose down

注意点

LocalStackのサービス制限について

docker-compose.ymlでSERVICES環境変数を使ってLocalStackのサービスを制限する場合、dynamodbのみに限定しないでください。

❌ 避けるべき設定例:

environment:
  - SERVICES=dynamodb  # これは動作しません

理由: cdklocalの認証処理ではSTS（Security Token Service）などの追加サービスが必要です。サービスを制限すると、以下のようなわかりづらいエラーが発生します：

Unable to resolve AWS account to use. It must be either configured when you define your CDK Stack, or through the environment

推奨: SERVICES環境変数を設定せず、LocalStackのデフォルト設定を使用してください。

関連リンク

• AWS CDK
• LocalStack
• setup-localstack Action
• aws-cdk-local

リソース

• DynamoDBテーブル: cdk-localstack-table