Configuration

drive-apig resolves configuration through a layered system: serverless.common.yml env vars → SSM Parameter Store → Secrets Manager → runtime SSMConfigResolver.

Config resolution

flowchart TD
  YAML["serverless.yml<br/>${env:..., 'ssm:...'}"] --> DEPLOY["Deploy"]
  YAML --> LOCAL["Local dev"]
  DEPLOY --> LAMBDA["process.env"]
  LOCAL --> ENV[".env.local<br/>(via yarn gen-env)"]
  LAMBDA --> RESOLVER["SSMConfigResolver"]
  ENV --> RESOLVER
  RESOLVER --> EXT["Parameters & Secrets<br/>Extension :2773"]
  EXT --> SSM["SSM"]
  EXT --> SM["Secrets Manager"]
  RESOLVER --> CODE["Handler"]

1. Declare in serverless.yml

Environment variables reference SSM paths. The ${env:VAR, "ssm:..."} pattern lets local dev override with a plain env var while deployed Lambdas read from SSM:

environment:
  apiKey: ${env:API_KEY, "ssm:/shared/drive/ext/service/apikey"}

At deploy time, the Lambda environment variable must still carry an ssm: reference when the handler expects runtime resolution. SSMConfigResolver fetches only values that start with ssm:; plain env values are treated as already resolved overrides.

2. Local dev — .env.local

For local development, generate .env.local files with actual SSM values:

yarn gen-env <service>                    # default: staging profile, dev stage
yarn gen-env <service> --stage staging    # stage-specific params
yarn gen-env <service> --profile aws-drive-prod-admin

This reads the service's serverless.yml, extracts all SSM references, fetches actual values from AWS, and writes .env.local into the service directory. When serverless-offline runs, dotenv/config loads .env.local so process.env.API_KEY resolves locally without hitting SSM.

3. Runtime — SSMConfigResolver

Deployed Lambdas use SSMConfigResolver to fetch values at runtime (with caching via the Parameters-and-Secrets Lambda Extension on port 2773):

const config = await SSMConfigResolver.resolve({
  apiKey: process.env.apiKey,
  cfApiToken: process.env.cfApiToken,
})

The extension caches responses (1-hour TTL by default), so repeated handler invocations don't re-fetch from SSM.

SSM parameter hierarchy

• Shared: /shared/drive/ext/{service}/{parameter} — cross-account, cross-env
• Stage-specific: /{stage}/drive/{service}/{parameter} — dev/staging/prod

Pages