Parameters

Warning

This page refers to an unreleased and upcoming utility. Please refer to this GitHub milestone for the latest updates.

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 base 64 encoded strings
• Bring Your Own Parameter Store Provider

Getting started

The Parameters Utility helps to retrieve parameters from the System Manager Parameter Store (SSM), secrets from the Secrets Manager, and application configuration from AppConfig. Additionally, the utility also offers support for a DynamoDB provider, enabling the retrieval of arbitrary parameters from specified tables.

Installation

Note

This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only the SDK packages you need and keep your bundle size small.

Depending on the provider you want to use, install the library and the corresponding AWS SDK package:

SSMProviderSecretsProviderAppConfigProviderDynamoDBProvider

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

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

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

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

Tip

If you are using the nodejs18.x runtime, the AWS SDK for JavaScript v3 is already installed and you can install the utility only.

IAM Permissions

This utility requires additional permissions to work as expected.

Note

Different parameter providers require different permissions.

Provider	Function/Method	IAM Permission
SSM	getParameter, SSMProvider.get	ssm:GetParameter
SSM	getParameters, SSMProvider.getMultiple	ssm:GetParametersByPath
SSM	getParametersByName, SSMProvider.getParametersByName	ssm:GetParameter and ssm:GetParameters
SSM	If using decrypt: true	You must add an additional permission kms:Decrypt
Secrets	getSecret, SecretsProvider.get	secretsmanager:GetSecretValue
DynamoDB	DynamoDBProvider.get	dynamodb:GetItem
DynamoDB	DynamoDBProvider.getMultiple	dynamodb:Query
AppConfig	getAppConfig, AppConfigProvider.getAppConfig	appconfig:GetLatestConfiguration and appconfig:StartConfigurationSession

Fetching parameters

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 either:

• getParameters to recursively fetch all parameters by path.
• getParametersByName to fetch distinct parameters by their full name. It also accepts custom caching, transform, decrypt per parameter.

getParametersgetParametersByName

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}`);
  }
};

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
import type {
  SSMGetParametersByNameOptionsInterface
} from '@aws-lambda-powertools/parameters/ssm';

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
};

export const handler = async (): Promise<void> => {
  // This returns an object with the parameter name as key
  const parameters = await getParametersByName(props, { maxAge: 60 });
  for (const [ key, value ] of Object.entries(parameters)) {
    console.log(`${key}: ${value}`);
  }
};

getParametersByName supports graceful error handling

By default, the provider will throw a GetParameterError when any parameter fails to be fetched. You can override it by setting throwOnError: false.

When disabled, instead the provider will take the following actions:

• Add failed parameter name in the _errors key, e.g., { _errors: [ '/param1', '/param2' ] }
• Keep only successful parameter names and their values in the response
• Throw GetParameterError if any of your parameters is named _errors

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';
import type {
  SSMGetParametersByNameOptionsInterface
} from '@aws-lambda-powertools/parameters/ssm';

const props: Record<string, SSMGetParametersByNameOptionsInterface> = {
  '/develop/service/commons/telemetry/config': { maxAge: 300, transform: 'json' },
  '/this/param/does/not/exist': {}, // <- Example of non-existent parameter
};

export const handler = async (): Promise<void> => {
  const {
    _errors: errors,
    ...parameters
  } = await getParametersByName(props, { throwOnError: false });

  // 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}`);
  }
};

Fetching secrets

You can fetch secrets stored in Secrets Manager using getSecrets.

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 app configurations

You can fetch application configurations in AWS AppConfig using getAppConfig.

The following will retrieve the latest version and store it in the cache.

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);
};

Advanced

Adjusting cache TTL

Tip

maxAge parameter is also available in high level functions like getParameter, getSecret, etc.

By default, the provider will cache parameters retrieved in-memory for 5 seconds.

You can adjust how long values should be kept in cache by using the param maxAge, when using get() or getMultiple() methods across all providers.

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a single parameter
  const parameter = await parametersProvider.get('/my/parameter', { maxAge: 60 }); // 1 minute
  console.log(parameter);

  // Retrieve multiple parameters from a path prefix
  const parameters = await parametersProvider.getMultiple('/my/path/prefix', { maxAge: 120 }); // 2 minutes
  for (const [ key, value ] of Object.entries(parameters || {})) {
    console.log(`${key}: ${value}`);
  }
};

Always fetching the latest

If you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the forceFetch parameter.

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

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

Built-in provider class

For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use their respective Provider Classes directly.

Tip

This can be used to retrieve values from other regions, change the retry behavior, etc.

SSMProvider

import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
import type { SSMClientConfig } from '@aws-sdk/client-ssm';

const clientConfig: SSMClientConfig = { region: 'us-east-1' };
const parametersProvider = new SSMProvider({ clientConfig });

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

  // Retrieve multiple parameters from a path prefix
  const parameters = await parametersProvider.getMultiple('/my/path/prefix');
  for (const [ key, value ] of Object.entries(parameters || {})) {
    console.log(`${key}: ${value}`);
  }
};

The AWS Systems Manager Parameter Store provider supports two additional arguments for the get() and getMultiple() methods:

Parameter	Default	Description
decrypt	false	Will automatically decrypt the parameter (see required IAM Permissions).
recursive	true	For getMultiple() only, will fetch all parameter values recursively based on a path prefix.

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  const decryptedValue = await parametersProvider.get('/my/encrypted/parameter', { decrypt: true });
  console.log(decryptedValue);

  const noRecursiveValues = await parametersProvider.getMultiple('/my/path/prefix', { recursive: false });
  for (const [ key, value ] of Object.entries(noRecursiveValues || {})) {
    console.log(`${key}: ${value}`);
  }
};

SecretsProvider

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
import type { SecretsManagerClientConfig } from '@aws-sdk/client-secretsmanager';

const clientConfig: SecretsManagerClientConfig = { region: 'us-east-1' };
const secretsProvider = new SecretsProvider({ clientConfig });

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

AppConfigProvider

The AWS AppConfig provider requires two arguments when initialized:

Parameter	Mandatory in constructor	Alternative	Description
application	No	POWERTOOLS_SERVICE_NAME env variable	The application in which your config resides.
environment	Yes	(N/A)	The environment that corresponds to your current config.

import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
import type { AppConfigDataClientConfig } from '@aws-sdk/client-appconfigdata';

const clientConfig: AppConfigDataClientConfig = { region: 'us-east-1' };
const configsProvider = new AppConfigProvider({
  application: 'my-app',
  environment: 'my-env',
  clientConfig,
});

export const handler = async (): Promise<void> => {
  // Retrieve a config
  const config = await configsProvider.get('my-config');
  console.log(config);
};

DynamoDBProvider

The DynamoDB Provider does not have any high-level functions and needs to know the name of the DynamoDB table containing the parameters.

DynamoDB table structure for single parameters

For single parameters, you must use id as the partition key for that table.

Example

DynamoDB table with id partition key and value as attribute

id	value
my-parameter	my-value

With this table, await dynamoDBProvider.get('my-param') will return my-value.

handler.tsDynamoDB Local example

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);
};

You can initialize the DynamoDB provider pointing to DynamoDB Local using the endpoint field in the clientConfig parameter:

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

const dynamoDBProvider = new DynamoDBProvider({
      tableName: 'my-table',
      clientConfig: {
        endpoint: 'http://localhost:8000'
      },
});

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

DynamoDB table structure for multiple values parameters

You can retrieve multiple parameters sharing the same id by having a sort key named sk.

Example

DynamoDB table with id primary key, sk as sort key and value as attribute

id	sk	value
my-hash-key	param-a	my-value-a
my-hash-key	param-b	my-value-b
my-hash-key	param-c	my-value-c

With this table, await dynamoDBProvider.getMultiple('my-hash-key') will return a dictionary response in the shape of sk:value.

handler.tsvalues response object

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

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

export const handler = async (): Promise<void> => {
  /**
     * Retrieve multiple values by performing a Query on the DynamoDB table.
     * This returns a dict with the sort key attribute as dict key.
     */
  const values = await dynamoDBProvider.getMultiple('my-hash-key');
  for (const [ key, value ] of Object.entries(values || {})) {
    // key: param-a
    // value: my-value-a
    console.log(`${key}: ${value}`);
  }
};

{
  "param-a": "my-value-a",
  "param-b": "my-value-b",
  "param-c": "my-value-c"
}

Customizing DynamoDBProvider

DynamoDB provider can be customized at initialization to match your table structure:

Parameter	Mandatory	Default	Description
tableName	Yes	(N/A)	Name of the DynamoDB table containing the parameter values.
keyAttr	No	id	Hash key for the DynamoDB table.
sortAttr	No	sk	Range key for the DynamoDB table. You don't need to set this if you don't use the getMultiple() method.
valueAttr	No	value	Name of the attribute containing the parameter value.

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

const dynamoDBProvider = new DynamoDBProvider({
  tableName:'my-table',
  keyAttr:'key',
  sortAttr:'sort',
  valueAttr:'val'
});

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

Deserializing values with transform parameter

For parameters stored in JSON or Base64 format, you can use the transform argument for deserialization.

Info

The transform argument is available across all providers, including the high level functions.

High level functionsProviders

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

export const handler = async (): Promise<void> => {
  const valueFromJson = await getParameter('/my/json/parameter', { transform: 'json' });
  console.log(valueFromJson);
};

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';

const secretsProvider = new SecretsProvider();

export const handler = async (): Promise<void> => {
  // Transform a JSON string
  const json = await secretsProvider.get('my-secret-json', { transform: 'json' });
  console.log(json);

  // Transform a Base64 encoded string (e.g. binary)
  const binary = await secretsProvider.getMultiple('my-secret-binary', { transform: 'binary' });
  console.log(binary);
};

Partial transform failures with getMultiple()

If you use transform with getMultiple(), you can have a single malformed parameter value. To prevent failing the entire request, the method will return an undefined value for the parameters that failed to transform.

You can override this by setting the throwOnTransformError argument to true. If you do so, a single transform error will throw a TransformParameterError error.

For example, if you have three parameters, /param/a, /param/b and /param/c, but /param/c is malformed:

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  /**
   * This will display:
   * /param/a: [some value]
   * /param/b: [some value]
   * /param/c: undefined
   */
  const parameters = await parametersProvider.getMultiple('/param', { transform: 'json' });
  for (const [ key, value ] of Object.entries(parameters || {})) {
    console.log(`${key}: ${value}`);
  }

  try {
    // This will throw a TransformParameterError
    const parameters2 = await parametersProvider.getMultiple('/param', {
      transform: 'json',
      throwOnTransformError: true
    });
    for (const [ key, value ] of Object.entries(parameters2 || {})) {
      console.log(`${key}: ${value}`);
    }
  } catch (err) {
    console.error(err);
  }
};

Auto-transform values on suffix

If you use transform with getMultiple(), you might want to retrieve and transform parameters encoded in different formats.

You can do this with a single request by using transform: 'auto'. This will instruct any provider to to infer its type based on the suffix and transform it accordingly.

Info

transform: 'auto' feature is available across all providers, including the high level functions.

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  const values = await parametersProvider.getMultiple('/param', { transform: 'auto' });
  for (const [ key, value ] of Object.entries(values || {})) {
    console.log(`${key}: ${value}`);
  }
};

For example, if you have three parameters: two with the following suffixes .json and .binary and one without any suffix:

Parameter name	Parameter value
/param/a	[some encoded value]
/param/a.json	[some encoded value]
/param/a.binary	[some encoded value]

The return of await parametersProvider.getMultiple('/param', transform: 'auto'); call will be an object like:

{
  "a": [some encoded value],
  "a.json": [some decoded value],
  "b.binary": [some decoded value]
}

The two parameters with a suffix will be decoded, while the one without a suffix will be returned as is.

Passing additional SDK arguments

You can use a special sdkOptions object argument to pass any supported option directly to the underlying SDK method.

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
import type { GetSecretValueCommandInput } from '@aws-sdk/client-secrets-manager';

const secretsProvider = new SecretsProvider();

export const handler = async (): Promise<void> => {
  const sdkOptions: Partial<GetSecretValueCommandInput> = {
    VersionId: 'e62ec170-6b01-48c7-94f3-d7497851a8d2'
  };
  /**
   * The 'VersionId' argument will be passed to the underlying
   * `GetSecretValueCommand` call.
   */
  const secret = await secretsProvider.get('my-secret', { sdkOptions });
  console.log(secret);
};

Here is the mapping between this utility's functions and methods and the underlying SDK:

Provider	Function/Method	Client name	Function name
SSM Parameter Store	getParameter	@aws-sdk/client-ssm	GetParameterCommand
SSM Parameter Store	getParameters	@aws-sdk/client-ssm	GetParametersByPathCommand
SSM Parameter Store	SSMProvider.get	@aws-sdk/client-ssm	GetParameterCommand
SSM Parameter Store	SSMProvider.getMultiple	@aws-sdk/client-ssm	GetParametersByPathCommand
Secrets Manager	getSecret	@aws-sdk/client-secrets-manager	GetSecretValueCommand
Secrets Manager	SecretsProvider.get	@aws-sdk/client-secrets-manager	GetSecretValueCommand
AppConfig	AppConfigProvider.get	@aws-sdk/client-appconfigdata	StartConfigurationSessionCommand & GetLatestConfigurationCommand
AppConfig	getAppConfig	@aws-sdk/client-appconfigdata	StartConfigurationSessionCommand & GetLatestConfigurationCommand
DynamoDB	DynamoDBProvider.get	@aws-sdk/client-dynamodb	GetItemCommand
DynamoDB	DynamoDBProvider.getMultiple	@aws-sdk/client-dynamodb	QueryCommand

Bring your own AWS SDK v3 client

You can use the awsSdkV3Client parameter via any of the available Provider Classes.

Provider	Client
SSMProvider	new SSMClient();
SecretsProvider	new SecretsManagerClient();
AppConfigProvider	new AppConfigDataClient();
DynamoDBProvider	new DynamoDBClient();

When is this useful?

Injecting a custom AWS SDK v3 client allows you to apply tracing or make unit/snapshot testing easier, including SDK customizations.

SSMProviderSecretsProviderAppConfigProviderDynamoDBProvider

import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
import { SSMClient } from '@aws-sdk/client-ssm';

// construct your clients with any custom configuration
const ssmClient = new SSMClient({ region: 'us-east-1' });
// pass the client to the provider
const parametersProvider = new SSMProvider({ awsSdkV3Client: ssmClient });

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

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';

// construct your clients with any custom configuration
const secretsManagerClient = new SecretsManagerClient({ region: 'us-east-1' });
// pass the client to the provider
const secretsProvider = new SecretsProvider({ awsSdkV3Client: secretsManagerClient });

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

import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
import { AppConfigDataClient } from '@aws-sdk/client-appconfigdata';

// construct your clients with any custom configuration
const appConfigClient = new AppConfigDataClient({ region: 'us-east-1' });
// pass the client to the provider
const configsProvider = new AppConfigProvider({ awsSdkV3Client: appConfigClient });

export const handler = async (): Promise<void> => {
  const config = await configsProvider.get('my-config');
  console.log(config);
};

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

// construct your clients with any custom configuration
const dynamoDBClient = new DynamoDBClient({ region: 'us-east-1' });
// pass the client to the provider
const valuesProvider = new DynamoDBProvider({ awsSdkV3Client: dynamoDBClient });

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

Customizing AWS SDK v3 configuration

The clientConfig parameter enables you to pass in a custom config object when constructing any of the built-in provider classes.

Tip

You can use a custom session for retrieving parameters cross-account/region and for snapshot testing.

When using VPC private endpoints, you can pass a custom client altogether. It's also useful for testing when injecting fake instances.

import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
import type { SSMClientConfig } from '@aws-sdk/client-ssm';

const clientConfig: SSMClientConfig = { region: 'us-east-1' };
const parametersProvider = new SSMProvider({ clientConfig });

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

---

Last update: 2023-01-13