SSM & Secrets Manager

Configuration values are resolved in two places: by Serverless at deploy time, and by handlers at runtime through the AWS Parameters and Secrets Lambda Extension.

Deploy-time SSM

Use ${ssm:...} in serverless.yml for values that are safe to resolve during deployment and remain stable for the deployed function version.

yaml

provider:
  apiGateway:
    restApiId: ${ssm:/${self:provider.stage}/drive/apig/drive-api/id}
    restApiRootResourceId: ${ssm:/${self:provider.stage}/drive/apig/drive-api/root_resource_id}
  deploymentBucket:
    name: ${ssm:/${self:provider.stage}/drive/s3/sls-deployments/id}

Typical deploy-time values are REST API ids, root resource ids, deployment bucket names, table names, and queue names.

Runtime extension

Secrets and rotating partner credentials should be resolved at runtime. Lambdas include the Parameters and Secrets extension layer from custom.ssmExtension.layerArn, which exposes a local HTTP server on port 2773.

const res = await fetch(
  `http://localhost:2773/systemsmanager/parameters/get?name=${encodeURIComponent(name)}`,
  { headers: { 'X-Aws-Parameters-Secrets-Token': process.env.AWS_SESSION_TOKEN } }
)

Shared extension config from serverless.common.yml:

yaml

SSM_PARAMETER_STORE_TTL: 3600
SECRETS_MANAGER_TTL: 3600
PARAMETERS_SECRETS_EXTENSION_CACHE_ENABLED: "true"
PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE: 1000
PARAMETERS_SECRETS_EXTENSION_HTTP_PORT: 2773
PARAMETERS_SECRETS_EXTENSION_MAX_CONNECTIONS: 3

Secrets Manager

The same extension reads Secrets Manager through /secretsmanager/get?secretId=.... Common partner credentials include:

/shared/drive/ext/openrouter/athena/apikey
/shared/drive/ext/portkey/apikey
/shared/drive/ext/telesign/auth_token
/shared/drive/ext/freespee/signing_key
/shared/drive/ext/stratton/api_key
/shared/drive/ext/autograb/apikey

Local override pattern

Most services use ${env:VAR, "ssm:..."} so local development can inject a plain environment variable while deployed Lambdas read from SSM:

yaml

environment:
  autoGrabApiKey: ${env:AUTOGRAB_API_KEY, "ssm:/shared/drive/ext/autograb/apikey"}

Run yarn gen-env <service> from the repo root to generate a service .env.local from SSM references before using serverless-offline.

Runtime override table

${stage}-drive-api-ssm-config is a DynamoDB table used by some services as a fast stage-specific override store. Access is granted in serverless.common.yml through dynamodb:BatchGetItem and dynamodb:BatchWriteItem.