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，同时避免上下文缓存问题
• 环境验证 - 尽早验证配置
• 环境部署策略 - 环境的部署方式
• 安全基线 - 密钥管理原则

---

渐进式改进

如果开发者纠正了本技能本应避免的行为，请建议对本技能进行具体修订，以防止将来出现同样的纠正。