localstackでfree -> baseプランにあげる時に必要だった対応

はじめに

AWSの各種サービスをモックできるlocalstack。その設定時に個人的に詰まった点のメモです
LocalStackを使った開発で、Cognitoなどのbasic以上の機能が必要になった際のアップグレード対応についてのメモ。

前提条件

• Docker & Docker Compose環境
• LocalStack base/pro プランのライセンス
• 既存のLocalStack free版の設定

問題の発生

最初にCognito IDPを使用しようとした際、以下のような状況でした：

# ヘルスチェックの結果
curl http://localhost:4566/_localstack/health
{
  "services": {
    // ... 他のサービス
    "cognito-idp": "disabled", // 😢 利用できない
  },
  "edition": "community",      // 😢 community版として動作
  "version": "4.9.3.dev12"
}

認証トークンは環境変数で設定していたにも関わらず、Community版として起動していました。

解決手順

1. Docker Composeファイルの修正

最も重要な変更は、専用のProイメージを使用することでした。

# ❌ 変更前（free版）
services:
  localstack:
    image: localstack/localstack:latest
    environment:
      SERVICES: s3,logs,events,ses,kms
      # ... 他の設定

# ✅ 変更後（base/pro版）
services:
  localstack:
    image: localstack/localstack-pro:latest  # 👈 専用イメージが必要！
    environment:
      SERVICES: s3,logs,events,ses,kms,cognito-idp  # 👈 Cognitoを追加
      LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN:-}  # 👈 認証トークン
      ACTIVATE_PRO: "1"  # 👈 Pro機能を有効化
      # ... 他の設定

3. 環境変数の設定

.envファイル

# LocalStack authentication (Pro plan required for Cognito)
# Get your token from: https://app.localstack.cloud/workspace/auth-token
LOCALSTACK_AUTH_TOKEN="ls-your-actual-token-here" # ここLocalstack Cloudで取得したトークンを設定

4. 認証トークンの取得方法

1. LocalStack Cloud にログイン
2. Workspace → Auth Token ページへ移動
3. 表示されたトークンをコピーして.envファイルに設定

ハマったエラー

1. Community版として動作してしまう

原因: 通常イメージを使用している
解決: localstack/localstack-pro:latest に変更

2. 認証エラー

原因: トークンが無効または未設定
解決: LocalStack Cloud で最新トークンを取得

3. Cognitoサービスが見つからない

原因: SERVICESに追加し忘れ
解決: SERVICES に cognito-idp を追加

デバッグ方法

# コンテナ内の環境変数確認
docker compose exec localstack env | grep -E "(LOCALSTACK|AUTH|ACTIVATE)"

# ログ確認
docker compose logs localstack | grep -i "auth\|pro\|cognito"

まとめ

LocalStackのfree版からbase版へのアップグレードでは、単純に認証トークンを設定するだけでは不十分で、専用のProイメージの使用が必須でした。

参考リンク

• LocalStack Documentation
• LocalStack Cloud Console
• Docker Compose Environment Variables