A zero-dependency Node.js client for the AWS Lambda Parameters and Secrets Extension.
What this package does: This package's zero-dependency Client makes GET requests from your Lambda to the AWS Extension layer's localhost endpoint. It saves you the effort of building the URL, making the HTTP request and parsing the response.
What AWS does: The AWS Parameters and Secrets Lambda Extension is an AWS-managed Lambda Layer. It's one way for Lambdas to retrieve parameters from the AWS Parameter Store and retrieve secrets from AWS Secrets Manager. Instead of making SDK calls to these services directly, an Extension-enabled Lambda function makes a HTTP GET request to the Extension's localhost endpoint. The Extension makes the GetParameter and GetSecretValue SDK calls. It returns the JSON result in the HTTP response to the Lambda. The Extension also caches the results, which is its killer feature.
AWS-Parameters-and-Secrets-Lambda-Extension layer added.ssm:GetParameter or secrets:GetSecretValue permissions. Using the AWS Extension requires the same IAM permissions as making the SDK calls directly.npm install --save lambda-params-secrets
The package has zero runtime dependencies.
Instantiate a Client in your Lambda function handler. Call the Client's methods to get values:
// my_lambda_handler.ts
import { Client } from "lambda-params-secrets";
export async function handler(): Promise<void> {
const client = new Client();
const fooListParam: string[] = await client.stringListParameter(
"/my-app/config/foo-list",
);
console.log(fooListParam); // -> ["foo", "bar", "baz"]
}
Use Client methods to retrieve parameters and secrets values:
| Method | Options | Happy return value |
|---|---|---|
| stringParameter(name, options) | version, label | string |
| stringListParameter(name, options) | version, label | array of strings |
| secureStringParameter(name, options) | version, label, withDecryption | string |
| stringSecret(secretId, options) | versionId, versionStage | string |
| binarySecret(secretId, options) | versionId, versionStage | Buffer |
| stringSecretfromParameterStore(secretId, options) | version, label | string |
| binarySecretfromParameterStore(secretId, options) | version, label | Buffer |
The above methods return null if the Client receives an error response.
Want the whole response instead of just the value? Call parameterResponse(name, options) or secretResponse(name, options) to retrieve the Extension's full JSON response.
The Client options have sensible defaults. Instantiating a client with new Client() is a good starting point, which is equivalent to:
const client = new Client({
token: process.env.AWS_SESSION_TOKEN, // default value. AWS set this opaque value.
port: process.env.PARAMETERS_SECRETS_EXTENSION_HTTP_PORT, // default value. AWS sets this by default to 2773.
requester: new FetchRequester(), // default value. Bare-bones getter that uses the Node.js native fetch library. Use HttpRequester() for NodeJS runtimes < 18.
});
an unexpected error occurred while executing request message in the HTTP response. But the Extension sends useful error details to the Lambda's CloudWatch logs.http://localhost:2773/systemsmanager/parameters/get?name=%2Flambda-ext-test-param%2Fdummy-string
X-Aws-Parameters-Secrets-Token header value to AWS_SESSION_TOKEN.The AWS Extension responds with a JSON object:
{
"Parameter": {
"ARN": "arn:aws:ssm:us-east-1:123456789012:parameter/lambda-ext-test-param/dummy-string",
"DataType": "text",
"LastModifiedDate": "2022-11-16T08:22:40.362Z",
"Name": "/lambda-ext-test-param/dummy-string",
"Selector": null,
"SourceResult": null,
"Type": "String",
"Value": "my-string-param-value",
"Version": 1
},
"ResultMetadata": {}
}
Please submit Bug Reports and Feature Requests as issues. :tada: Pull Requests are also welcome! See CONTRIBUTING.md for details.
This code is made available under the MIT license.