v1.11.0

Summary

In this release we are excited to announce the General Availability of the Parameters utility 🎉 After almost three months of beta period we consider the utility ready for production workloads and consider the API stable.

Parameters

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

Fetching parameters from AWS SSM Parameter Store

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

npm install @aws-lambda-powertools/parameters @aws-sdk/client-ssm

Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the actions detailed in the documentation of the utility.

You can retrieve a single parameter using the getParameter() high-level function.

import { getParameter } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  // Retrieve a single parameter
  const parameter = await getParameter('/my/parameter');
  console.log(parameter);
};

For multiple parameters, you can use getParameters() to recursively fetch all parameters under a path:

import { getParameters } from '@aws-lambda-powertools/parameters/ssm';

export const handler = async (): Promise<void> => {
  /**
   * Retrieve multiple parameters from a path prefix recursively.
   * This returns an object with the parameter name as key
   */
  const parameters = await getParameters('/my/path/prefix');
  for (const [key, value] of Object.entries(parameters || {})) {
    console.log(`${key}: ${value}`);
  }
};

Alternatively, you can also fetch multiple parameters using their full name by using the getParametersByName() function.

Getting secrets from Amazon Secrets Manager

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

npm install @aws-lambda-powertools/parameters @aws-sdk/client-secrets-manager

Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the actions detailed in the documentation of the utility.

You can fetch secrets stored in Secrets Manager using 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);
};

Fetching configs from AWS AppConfig

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

npm install @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata

Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the actions detailed in the documentation of the utility.

You can fetch application configurations in AWS AppConfig using the getAppConfig() function:

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a configuration, latest version
  const config = await getAppConfig('my-configuration', {
    environment: 'my-env',
    application: 'my-app',
  });
  console.log(config);
};

Retrieving values from Amazon DynamoDB

To get started, install the library and the corresponding AWS SDK for JavaScript v3:

npm install @aws-lambda-powertools/parameters @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb

Next, review the IAM permissions attached to your AWS Lambda function and make sure you allow the actions detailed in the documentation of the utility.

You can retrieve a single parameter from DynamoDB using the DynamoDBProvider.get() method:

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

const dynamoDBProvider = new DynamoDBProvider({ tableName: 'my-table' });

export const handler = async (): Promise<void> => {
  // Retrieve a value from DynamoDB
  const value = await dynamoDBProvider.get('my-parameter');
  console.log(value);
};

For retrieving multiple parameters, you can use the DynamoDBProvider.getMultiple() method instead.

Learn More

If you want to learn more, check the post we have just published on the AWS Compute Blog: Retrieving parameters and secrets with Powertools for AWS Lambda (TypeScript)

Acknowledgements

A big thank you to all the people who contributed to this utility with PRs, questions, feedback, and bug reports.

Changes

• tests(tracer): update docs url for e2e tests (#1559) by @dreamorosi

🌟New features and non-breaking changes

• feat(idempotency): preserve original error when wrapping into IdempotencyPersistenceLayerError (#1552) by @am29d

📜 Documentation updates

• docs(parameters): release tasks + add docs on bring your own provider (#1565) by @dreamorosi
• chore(docs): add certible + logo (#1563) by @am29d
• chore(tests): upgrade @aws-sdk/* pacakges (#1561) by @dreamorosi
• chore(docs): update docs base origin url (#1551) by @hjgraca

🔧 Maintenance

• docs(parameters): release tasks + add docs on bring your own provider (#1565) by @dreamorosi
• chore(idempotency): remove decorators (#1554) by @dreamorosi
• chore(docs): add certible + logo (#1563) by @am29d
• chore(tests): upgrade @aws-sdk/* pacakges (#1561) by @dreamorosi

This release was made possible by the following contributors:

@am29d, @dreamorosi, @hjgraca and Release bot[bot]