Today, lambda powertools has released version 1.7.0. Although it is a beta developer preview, it is already very close to the GA version. This version includes a feature that I have been waiting for a long time, so I can't wait to use it and introduce it to you. This feature is called Parameters utility. This new utility allows you to retrieve one or more parameter values from a range of AWS services, while also helping you reduce the amount of custom code needed to handle caching, transformations, and error handling.
The Parameters utility provides high-level functions to retrieve one or multiple parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, AWS AppConfig, Amazon DynamoDB, or your own parameter store.
Key features
- Retrieve one or multiple parameters from the underlying provider
- Cache parameter values for a given amount of time (defaults to 5 seconds)
- Transform parameter values from JSON or base64 encoded strings
- Bring Your Own Parameter Store Provider
Getting started
To start testing the utility, install it from npm using the @aws-lambda-powertools/parameters@1.7.0-beta alias.
In addition, you will need to add the AWS SDK client for the parameter store you are planning to use. The Parameters utility supports AWS SDK v3 for JavaScript only which allows the utility to be modular, and you to install only the SDK packages you need and keep your bundle size small:
- SSM Parameters Store ->
@aws-sdk/client-ssm - Secrets Manager ->
@aws-sdk/client-secrets-manager - AppConfig ->
@aws-sdk/client-appconfigdata - DynamoDB ->
@aws-sdk/client-dynamodb @aws-sdk/util-dynamodb
Next, assign appropriate AWS Identity and Access Management (IAM) permissions to the Lambda function execution role of your Lambda function that allow retrieving parameters from the parameter store. You can see which permissions are needed for each action and store in the IAM Permissions section of the utility's docs.
In the section below we will use Secrets Manager as store to showcase different features of the Parameters utility. The same features are available for all other providers, as well as some others unique to each store. If you are interested in another store, skip to the utility docs.
Retrieving a single secret
To retrieve an individual parameter, the Parameters utility provides the getSecret function:
import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
export const handler = async (): Promise<void> => {
// Retrieve a single secret
const secret = await getSecret('my-secret');
console.log(secret);
}
Adjusting cache TTL
By default, the retrieved value will be cached in-memory for 5 seconds. This cached value is used for subsequent invocations of the Lambda function until it expires. If you want to keep the value around longer, the Parameters utility allows you to adjust the time-to-live (TTL) via the maxAge argument:
import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
export const handler = async (): Promise<void> => {
// Retrieve a single secret with a 60 seconds cache TTL
const secret = await getSecret('my-secret', { maxAge: 60 });
console.log(secret);
}
If instead you want to make sure that the latest value is always retrieved and cache is skipped, you can use the forceFetch option:
import { getSecret } from '@aws-lambda-powertools/parameters/secrets';
export const handler = async (): Promise<void> => {
// Retrieve a single secret skipping cache
const secret = await getSecret('my-secret', { forceFetch: true });
console.log(secret);
}
Decoding secrets stored in JSON or base64 format
If some of your secrets are stored in base64 or JSON, you can deserialize them via the Parameters utility’s transform argument:
import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
const secretsProvider = new SecretsProvider();
export const handler = async (): Promise<void> => {
// Retrieve a secret and deserialize it as JSON
const json = await secretsProvider.get('my-secret-json', { transform: 'json' });
console.log(json);
// Transform a base64 encoded string
const binary = await secretsProvider.getMultiple('my-secret-binary', { transform: 'binary' });
console.log(binary);
}
Customizing the AWS SDK
In some cases, you might want to use your own custom AWS SDK to retrieve values. This is useful in those instances in which you want to configure specific parameters or if you want to apply tracing. To do so, you can use the provider class directly:
import { Tracer } from "@aws-lambda-powertools/tracer";
import { SecretsProvider } from "@aws-lambda-powertools/parameters/secrets";
import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
// initialize the tracer
const tracer = new Tracer();
// construct your client and instrument it to emit tracing data
const secretsManagerClient = tracer.captureAWSv3Client(new SecretsManagerClient({}));
// pass the client to the SecretProvider
const secretProvider = new SecretsProvider({ awsSdkV3Client: secretsManagerClient });
export const handler = async (): Promise<void> => {
// this operation will now appear in your X-Ray traces and service map
const secret = await secretProvider.get('my-secret');
console.log(secret);
}
To learn more about all the features available for each provider, check the Parameters docs.
Other provider
The examples above are all secrets, and you can use the same approach to access configurations stored in AppConfig, SSM, or DynamoDB.
import { AppConfigProvider } from "@aws-lambda-powertools/parameters/appconfig";
import { SSMProvider } from "@aws-lambda-powertools/parameters/ssm";
import { DynamoDBProvider } from "@aws-lambda-powertools/parameters/dynamodb";
SSM Provider
For example, using SSM, you can retrieve multiple parameters at once and apply specific transformations or TTLs.
import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
import type { SSMGetParametersByNameOptionsInterface } from "@aws-lambda-powertools/parameters/types";
const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
'/develop/service/commons/telemetry/config': { maxAge: 300, transform: 'json' },
'/no_cache_param': { maxAge: 0 },
'/develop/service/payment/api/capture/url': {}, // When empty or undefined, it uses default values
'/this/param/does/not/exist': {}, // <- Example of non-existent parameter
};
export const handler = async (): Promise<void> => {
// This returns an object with the parameter name as key
const {
_errors: errors,
...parameters
} = await getParametersByName(props, { maxAge: 60 });
// Handle gracefully, since `/this/param/does/not/exist` will only be available in `_errors`
if (errors && errors.length) {
console.error(`Unable to retrieve parameters: ${errors.join(',')}`);
}
for (const [key, value] of Object.entries(parameters)) {
console.log(`${key}: ${value}`);
}
};