Class SSMProvider

Intro

The Parameters utility provides a SSMProvider that allows to retrieve parameters from AWS Systems Manager.

Getting started

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.

To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for AppConfig:

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

Basic usage

Retrieve a parameter from SSM:

Example

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

const parametersProvider = new SSMProvider();

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

If you want to retrieve a parameter without customizing the provider, you can use the getParameter function instead.

You can also retrieve parameters at once. If you want to get multiple parameters under the same path, you can use the getMultiple method.

Example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
 // Retrieve multiple parameters by path from SSM
 const parameters = await parametersProvider.getMultiple('/my-parameters-path');
};

If you don't need to customize the provider, you can also use the {@link getParameters} function instead.

If instead you want to retrieve multiple parameters by name, you can use the `getParametersByName` method.

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve multiple parameters by name from SSM
  const parameters = await parametersProvider.getParametersByName({
    '/my-parameter-1': {}, // Use default options
    '/my-parameter-2': { transform: 'json' }, // Parse the value as JSON
  });
};

If you don't need to customize the provider, you can also use the {@link getParametersByName} function instead.

Advanced usage

Caching

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 maxAge parameter.

@example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and cache it for 10 seconds
  const parameter = await parametersProvider.get('/my-parameter', { maxAge: 10 });
  // Retrieve multiple parameters by path and cache them for 20 seconds
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { maxAge: 20 });
};

When using the getParametersByName method, you can set a different maxAge for each parameter or set a default maxAge for all parameters.

@example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve multiple parameters by name and cache them individually
  const parameters = await parametersProvider.getParametersByName({
    '/my-parameter-1': { maxAge: 10 }, // Cache for 10 seconds
    '/my-parameter-2': { maxAge: 20 }, // Cache for 20 seconds
  });
  // Retrieve multiple parameters by name and cache them all for 20 seconds
  const parameters = await parametersProvider.getParametersByName({
    '/my-parameter-1': {},
    '/my-parameter-2': {},
  }, { maxAge: 20 });
};

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

@example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and skip cache
  const parameter = await parametersProvider.get('/my-parameter', { forceFetch: true });
  // Retrieve multiple parameters and skip cache
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { forceFetch: true });
};

Likewise, you can use the forceFetch parameter with the getParametersByName method both for individual parameters and for all parameters.

Decryption

If you want to retrieve a parameter that is encrypted, you can use the decrypt parameter. This parameter is compatible with get, getMultiple and getParametersByName.

@example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and decrypt it
  const parameter = await parametersProvider.get('/my-parameter', { decrypt: true });
  // Retrieve multiple parameters and decrypt them
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { decrypt: true });
};

Transformations

For parameters stored as JSON you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.

@example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and parse it as JSON
  const parameter = await parametersProvider.get('/my-parameter', { transform: 'json' });
  // Retrieve multiple parameters and parse them as JSON
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { transform: 'json' });
};

For parameters that are instead stored as base64-encoded binary data, you can use the transform argument set to binary for decoding. This will return a decoded string.

@example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a base64-encoded string and decode it
  const parameter = await parametersProvider.get('/my-parameter', { transform: 'binary' });
  // Retrieve multiple base64-encoded strings and decode them
  const parameters = await parametersProvider.getMultiple('/my-parameters-path', { transform: 'binary' });
};

Both type of transformations are compatible also with the getParametersByName method.

Extra SDK options

When retrieving parameters, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter.

@example

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

const parametersProvider = new SSMProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a parameter and pass extra options to the AWS SDK v3 for JavaScript client
  const parameter = await parametersProvider.get('/my-parameter', {
    sdkOptions: {
      WithDecryption: true,
    },
  });
};

The objects accept the same options as respectively the AWS SDK v3 for JavaScript GetParameter command and the AWS SDK v3 for JavaScript GetParametersByPath command.

Customize AWS SDK v3 for JavaScript client

By default, the provider will create a new SSM client using the default configuration.

You can customize the client by passing a custom configuration object to the provider.

@example

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

const parametersProvider = new SSMProvider({
  clientConfig: { region: 'eu-west-1' },
});

This object accepts the same options as the AWS SDK v3 for JavaScript SSM client constructor.

Otherwise, if you want to use a custom client altogether, you can pass it to the provider.

@example

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

const client = new SSMClient({ region: 'eu-west-1' });
const parametersProvider = new SSMProvider({
  awsSdkV3Client: client,
});

This object must be an instance of the AWS SDK v3 for JavaScript SSM client.

For more usage examples, see our documentation.