Back to Details

ssm-runtime-configuration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SSM Runtime Configuration

SSM运行时配置

This is a reference pattern. Learn from the approach, adapt to your context — don't copy verbatim.
Audience: Service developers (Lambda, ECS, frontend). If you're using CDK to deploy infrastructure, see CDK Bootstrap Configuration.
Problem: Configuration scattered across .env files, CI/CD secrets, and cloud resources becomes out of sync and hard to manage.
Solution: Use AWS SSM Parameter Store as single source of truth for runtime configuration, with minimal .env files only for local development overrides.
这是参考模式。请学习该方法，根据你的实际场景调整，不要逐字照搬。
受众：服务开发者（Lambda、ECS、前端）。如果你使用CDK部署基础设施，请查看CDK Bootstrap Configuration。
问题：分散在.env文件、CI/CD密钥和云资源中的配置容易出现不同步，难以管理。
解决方案：使用AWS SSM Parameter Store作为运行时配置的唯一可信源，仅保留最小化的.env文件用于本地开发配置覆盖。

Pattern

模式

Architecture:
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)
Key Components:
  • SSM Parameter Store: Runtime configuration for all environments
  • infrastructure/.env: Bootstrap config (AWS account, region) - deployment only
  • service/.env.local: Local development overrides - optional, not committed
架构:
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：本地开发覆盖配置 - 可选，不提交到代码仓库

Why This Pattern?

为什么使用该模式？

Benefits:
  • Single Source of Truth: All runtime config in SSM, no sync issues
  • Environment Isolation: Separate parameters per environment
  • No Secrets in Repo: Sensitive values stay in AWS
  • CI/CD Compatible: Pipelines fetch from SSM, no local files needed
  • Runtime Flexibility: Change config without redeployment
Use Cases:
  • AWS serverless applications
  • Multi-environment deployments
  • Projects with sensitive configuration
  • CI/CD pipelines
优势:
  • 唯一可信源：所有运行时配置都存放在SSM中，无同步问题
  • 环境隔离：每个环境对应独立的参数
  • 仓库无密钥：敏感值全部保存在AWS中
  • 兼容CI/CD：流水线直接从SSM拉取配置，无需本地文件
  • 运行时灵活性：无需重新部署即可修改配置
适用场景:
  • AWS无服务应用
  • 多环境部署
  • 包含敏感配置的项目
  • CI/CD流水线

Implementation

实现方案

SSM Namespace Structure:
/{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
Bootstrap Configuration (infrastructure/.env):
bash
undefined
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):
bash
undefined

Minimal config for CDK deployment

Minimal config for CDK deployment

CDK_DEFAULT_ACCOUNT=123456789012 CDK_DEFAULT_REGION=eu-central-1

**Local Overrides** (frontend/.env.local):
```bash
CDK_DEFAULT_ACCOUNT=123456789012 CDK_DEFAULT_REGION=eu-central-1

**本地覆盖配置** (frontend/.env.local):
```bash

Override SSM values for local development only

Override SSM values for local development only

API_ENDPOINT=http://localhost:3000

**Retrieving Parameters**:
```typescript
// 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;
}
API_ENDPOINT=http://localhost:3000

**参数获取逻辑**:
```typescript
// 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;
}

File Strategy

文件管理策略

What to Commit:
  • ✅ 
    infrastructure/.env
    - Bootstrap config (no secrets)
  • ✅ 
    .env_TEMPLATE
    files - Documentation
  • ❌ 
    .env.local
    - Local overrides (gitignored)
  • ❌ 
    .env.dev
    , 
    .env.prod
    - Runtime config (in SSM instead)
Template Files:
bash
undefined
需要提交到仓库的文件:
  • ✅ 
    infrastructure/.env
    - 引导配置（不含密钥）
  • ✅ 
    .env_TEMPLATE
    文件 - 配置说明文档
  • ❌ 
    .env.local
    - 本地覆盖配置（加入gitignore）
  • ❌ 
    .env.dev
    , 
    .env.prod
    - 运行时配置（改为存放在SSM中）
模板文件示例:
bash
undefined

.env_TEMPLATE

.env_TEMPLATE

Purpose: Document expected variables

Purpose: Document expected variables

Instructions: Copy to .env.local and customize

Instructions: Copy to .env.local and customize

API Endpoint (from SSM by default)

API Endpoint (from SSM by default)

API_ENDPOINT=http://localhost:3000

API_ENDPOINT=http://localhost:3000


---

---

CLI Integration

CLI集成

bash
undefined
bash
undefined

Get single parameter

Get single parameter

ssm-params get /{project-id}/dev/frontend/API_ENDPOINT
ssm-params get /{project-id}/dev/frontend/API_ENDPOINT

Export all parameters for service

Export all parameters for service

ssm-params export-service dev frontend
ssm-params export-service dev frontend

Output as .env format

Output as .env format

ssm-params export-service dev frontend > .env

---
ssm-params export-service dev frontend > .env

---

Tradeoffs

优劣权衡

Pros:
  • Single source of truth
  • No sync issues
  • Secure secret storage
Cons:
  • Requires AWS access for local development
  • Slightly slower startup (network call to SSM)
  • More complex than simple .env files
When NOT to Use:
  • Non-AWS projects
  • Simple applications with no sensitive config
  • Projects without multiple environments
优点:
  • 唯一可信源
  • 无同步问题
  • 安全的密钥存储
缺点:
  • 本地开发需要AWS访问权限
  • 应用启动速度稍慢（需要调用SSM的网络请求）
  • 比直接使用简单的.env文件更复杂
不适用场景:
  • 非AWS项目
  • 无敏感配置的简单应用
  • 没有多环境的项目

Related Patterns

相关模式

  • CDK Bootstrap Configuration - For CDK projects: how to write outputs to SSM without causing context caching issues
  • Environment Validation - Validate config early
  • Environment Deployment Strategy - How environments are deployed
  • Security Baseline - Secret management principles
  • CDK Bootstrap Configuration - 适用于CDK项目：如何将输出写入SSM而不引发上下文缓存问题
  • Environment Validation - 尽早验证配置
  • Environment Deployment Strategy - 环境部署方案
  • Security Baseline - 密钥管理原则

Progressive Improvement

渐进式优化

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.
如果开发者纠正了本规范本应预防的错误行为，请针对本规范提出具体的修订建议，避免未来再次出现同类问题。