ssm-runtime-configuration

SSM ランタイム設定

これは参考パターンです。 アプローチを参考にし、状況に合わせて応用してください。そのままコピーしないでください。

対象読者：サービス開発者（Lambda、ECS、フロントエンド）。CDK を使ってインフラをデプロイする場合は、CDK ブートストラップ設定を参照してください。

課題：.env ファイル、CI/CD のシークレット、クラウドリソースに設定が分散すると、値が同期されなくなり、管理が難しくなります。

解決策：AWS SSM Parameter Store をランタイム設定の唯一の信頼できる情報源として使い、.env ファイルはローカル開発時の上書きに限って最小限にします。

---

パターン

アーキテクチャ：

Infrastructure Deployment → Creates/Updates SSM Parameters
                                      ↓
                            SSM Parameter Store
                            (Single Source of Truth)
                                      ↓
                    ┌─────────────────┴─────────────────┐
                    ↓                                   ↓
            Local Development                    CI/CD Pipeline
         (with .env.local overrides)          (SSM values only)

主要コンポーネント：

• SSM Parameter Store：すべての環境のランタイム設定
• infrastructure/.env：ブートストラップ設定（AWS アカウント、リージョン）。デプロイ専用
• service/.env.local：ローカル開発時の上書き。任意。コミットしません

---

このパターンを使う理由

メリット：

• 唯一の信頼できる情報源：すべてのランタイム設定を SSM に集約し、同期の問題をなくします
• 環境の分離：環境ごとにパラメーターを分けます
• リポジトリにシークレットを置かない：機密値は AWS に保持します
• CI/CD に対応：パイプラインが SSM から取得するため、ローカルファイルは不要です
• ランタイムの柔軟性：再デプロイせずに設定を変更できます

ユースケース：

• AWS サーバーレスアプリケーション
• 複数環境へのデプロイ
• 機密設定を含むプロジェクト
• CI/CD パイプライン

---

実装

SSM 名前空間の構造：

/{project-id}/{environment}/{service}/VARIABLE_NAME

Examples:
/my-app/local/frontend/API_ENDPOINT
/my-app/dev/frontend/API_ENDPOINT
/my-app/prod/backend/DATABASE_URL

ブートストラップ設定（infrastructure/.env）：

# Minimal config for CDK deployment
CDK_DEFAULT_ACCOUNT=123456789012
CDK_DEFAULT_REGION=eu-central-1

ローカルでの上書き（frontend/.env.local）：

# Override SSM values for local development only
API_ENDPOINT=http://localhost:3000

パラメーターの取得：

// At application startup
import { SSMClient, GetParameterCommand } from '@aws-sdk/client-ssm';

const ssmClient = new SSMClient({ region: process.env.AWS_REGION });

async function getConfig(environment: string, service: string) {
  const path = `/${PROJECT_ID}/${environment}/${service}/`;
  // Fetch all parameters under path
  // Apply .env.local overrides if environment === 'local'
  return config;
}

---

ファイルの扱い

コミットするファイル：

• ✅ infrastructure/.env - ブートストラップ設定（シークレットなし）
• ✅ .env_TEMPLATE ファイル - ドキュメント
• ❌ .env.local - ローカルでの上書き（gitignore 対象）
• ❌ .env.dev、.env.prod - ランタイム設定（代わりに SSM に保存）

テンプレートファイル：

# .env_TEMPLATE
# Purpose: Document expected variables
# Instructions: Copy to .env.local and customize

# API Endpoint (from SSM by default)
# API_ENDPOINT=http://localhost:3000

---

CLI との連携

# Get single parameter
ssm-params get /{project-id}/dev/frontend/API_ENDPOINT

# Export all parameters for service
ssm-params export-service dev frontend

# Output as .env format
ssm-params export-service dev frontend > .env

---

トレードオフ

メリット：

• 唯一の信頼できる情報源
• 同期の問題がない
• シークレットを安全に保存

デメリット：

• ローカル開発にも AWS へのアクセスが必要です
• 起動が若干遅くなります（SSM へのネットワーク呼び出し）
• シンプルな .env ファイルより複雑です

使用しない場合：

• AWS を使わないプロジェクト
• 機密設定のないシンプルなアプリケーション
• 複数の環境がないプロジェクト

---

関連パターン

• CDK ブートストラップ設定 - CDK プロジェクト向け：コンテキストのキャッシュに関する問題を起こさずに、出力を SSM に書き込む方法
• 環境の検証 - 設定を早期に検証します
• 環境のデプロイ戦略 - 環境のデプロイ方法
• セキュリティベースライン - シークレット管理の原則

---

継続的な改善

開発者が、このスキルで防止できるはずの動作を修正した場合は、同じ修正が今後必要にならないよう、このスキルに加える具体的な改訂を提案してください。