@kmhgmbh/parameters-secrets-lambda-utils

This package is designed as a utility package for AWS Lambda projects. It provides boilerplate code for standardized access to the following resources:

AWS Systems Manager parameter store values
AWS Secrets Manager secret values

Access to these resources is realized through the AWS Parameters and Secrets Lambda extension.

Technology

Typescript
Node.js 18

Project integration

Add this extension to your dependencies:

npm i @kmhgmbh/parameters-secrets-lambda-utils

Configure the usage of the required extension in your CloudFormation template or utilized wrapper template. Example for a serverless.yml:

# ...
provider:
  # ...
  layers:
    - 'arn:aws:lambda:eu-central-1:187925254637:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11'
    # ...
  # ...
# ...

Usage

This package exposes the following functions:

`getParameterValue(name: string): Promise<string>`

Retrieves an AWS Systems Manager parameter store value name represents either the parameter's full name or path (in case the parameter is part of a hierarchy). Note: The extension currently does not support fetching full hierarchy trees.

`getSecretValue(secretId: string): Promise<Record<string, string>>`

Retrieves an AWS Secrets Manager secret value by its secret ID. Always retrieves the latest version of the secret.

`invalidateLocalCaches(): void`

Resets the caches for local parameters and secrets.

Local development / testing with this package

When developing or testing locally, you probably won't be able to access the SSM or Secrets Manager APIs or will try to avoid them for financial reasons. You can utilize specific ENV variables in conjunction with JSON files to simulate parameters and secrets fetching.

This package recognizes a local environment with the following conditions:

process.env.IS_LOCAL === 'true', as set by serverless invoke local
process.env.IS_OFFLINE === 'true', as set by the serverless-offline plugin when running a local API Gateway
process.env.AWS_SAM_LOCAL === 'true', as set by sam invoke local when running a local CDK lambda stack function

If you locally execute a Lambda function in another way, apply one of the ENV variables on your own to activate local files detection.

A recognized local environment triggers console warnings when the SSM or Secrets Manager APIs are still accessed; you can disable these warnings by setting the ENV variable PSLU_DISABLE_LOCAL_FETCH_WARNING=true to a truthy value.

Caching

While the Lambda layer caches results from the APIs, it doesn't cache local results. You can enable a local file results cache with PSLU_ENABLE_LOCAL_CACHE=true in order to minimize file readings.

Local parameters

You can create a JSON file that represents your SSM configuration tree and place it in your project's working directory. Set process.env.PSLU_LOCAL_PARAMETERS to the filename and extension, e.g. ssm.json, to fetch values from it.

Note: The parameter is read as-is, so theoretically you can also specify a value with directory separators, e.g. local/ssm.json. However, some operating systems may not support this approach.

Example file

{
  "Config": {
    "MyApp": {
      "SomeApi": {
        "ClientId": "asdfasdf",
        "ClientSecret": "fdsafdsa"
      }
    }
  }
}

Local secrets

For each secret ID, you can create a JSON file that represents your Secrets Manager key-value collection and place it in your project's working directory. The file name must consist of a specific prefix set in PSLU_SECRETS_PREFIX and the secret ID you want to fetch, connected by a dot, e.g. local-secrets.myApp.json for PSLU_SECRETS_PREFIX=local-secrets and secret ID "myApp". This makes it technically possible to access different secret collections in the same project.

Note: The prefix is read as-is, so theoretically you can also specify a value with directory separators, e.g. local/secrets. However, some operating systems may not support this approach.

Example secrets file

{
  "someSecret":"SomeSecretValue",
  "someOtherSecret":"SomeOtherSecretValue",
}

ENV variables reference

For ENV variables that are specific to the wrapped Lambda layer, see here.

Variable	Values	Description
`PSLU_DISABLE_LOCAL_FETCH_WARNING`	`true`\|`false`\|`undefined`	When set to `true`, disables warnings when fetching from APIs in a local enviroment
`PSLU_ENABLE_LOCAL_CACHE`	`true`\|`false`\|`undefined`	When set to `true`, enables caching of local parameters and secrets
`PSLU_LOCAL_PARAMETERS`	`string`	File name of local parameters JSON
`PSLU_SECRETS_PREFIX`	`string`	File name prefix of local secrets JSONs