@kmhgmbh/parameters-secrets-lambda-utils
v1.5.0
Published
Boilerplate code for the AWS Parameters and Secrets Lambda extension layer
Downloads
262
Readme
@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 byserverless invoke local
process.env.IS_OFFLINE === 'true'
, as set by theserverless-offline
plugin when running a local API Gatewayprocess.env.AWS_SAM_LOCAL === 'true'
, as set bysam 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 |