Use AWS Secrets Manager secrets in AWS Lambda functions - AWS Secrets Manager

Use AWS Secrets Manager secrets in AWS Lambda functions

You can use the AWS Parameters and Secrets Lambda Extension to retrieve and cache AWS Secrets Manager secrets in Lambda functions without using an SDK. Retrieving a cached secret is faster than retrieving it from Secrets Manager. Because there is a cost for calling Secrets Manager APIs, using a cache can reduce your costs. The extension can retrieve both Secrets Manager secrets and Parameter Store parameters. For information about Parameter Store, see Parameter Store integration with Lambda extensions in the AWS Systems Manager User Guide.

A Lambda extension is a companion process that adds to the capabilities of a Lambda function. For more information, see Lambda extensions in the Lambda Developer Guide. For information about using the extension in a container image, see Working with Lambda layers and extensions in container images . Lambda logs execution information about the extension along with the function by using Amazon CloudWatch Logs. By default, the extension logs a minimal amount of information to CloudWatch. To log more details, set the environment variable PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL to debug.

To provide the in-memory cache for parameters and secrets, the extension exposes a local HTTP endpoint, localhost port 2773, to the Lambda environment. You can configure the port by setting the environment variable PARAMETERS_SECRETS_EXTENSION_HTTP_PORT.

Lambda instantiates separate instances corresponding to the concurrency level that your function requires. Each instance is isolated and maintains its own local cache of your configuration data. For more information about Lambda instances and concurrency, see Managing concurrency for a Lambda function in the Lambda Developer Guide.

To add the extension for ARM, you must use the arm64 architecture for your Lambda function. For more information, see Lambda instruction set architectures in the Lambda Developer Guide. The extension supports ARM in the following Regions: Asia Pacific (Mumbai), US East (Ohio), Europe (Ireland), Europe (Frankfurt), Europe (Zurich), US East (N. Virginia), Europe (London), Europe (Spain), Asia Pacific (Tokyo), US West (Oregon), Asia Pacific (Singapore), Asia Pacific (Hyderabad), and Asia Pacific (Sydney).

The extension uses an AWS client. For information about configuring the AWS client, see Settings reference in the AWS SDK and Tools Reference Guide. If your Lambda function runs in a VPC, you need to create a VPC endpoint so that the extension can make calls to Secrets Manager. For more information, see Using an AWS Secrets Manager VPC endpoint.

To use the AWS Parameters and Secrets Lambda Extension
  1. Add the layer to your function by doing one of the following:

    • Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.

      1. Choose your function, choose Layers, and then choose Add a layer.

      2. On the Add layer page, for AWS layers, choose AWS Parameters and Secrets Lambda Extension, and then choose Add.

    • Use the following AWS CLI command with the appropriate ARN for your Region. For a list of ARNs, see AWS Parameters and Secrets Lambda Extension ARNs in the AWS Systems Manager User Guide.

      aws lambda update-function-configuration \ --function-name my-function \ --layers LayerARN
  2. Grant permissions to the Lambda execution role to be able to access secrets:

  3. Configure the cache with Lambda environment variables.

  4. To retrieve secrets from the extension cache, you first need to add the X-AWS-Parameters-Secrets-Token to the request header. Set the token to AWS_SESSION_TOKEN, which is provided by Lambda for all running functions. Using this header indicates that the caller is within the Lambda environment.

    The following Python example shows how to add the header.

    import os headers = {"X-Aws-Parameters-Secrets-Token": os.environ.get('AWS_SESSION_TOKEN')}
  5. To retrieve a secret within the Lambda function, use one of the following HTTP GET requests:

    • To retrieve a secret, for secretId, use the ARN or name of the secret.

      GET: /secretsmanager/get?secretId=secretId
    • To retrieve the previous secret value or a specific version by staging label, for secretId, use the ARN or name of the secret, and for versionStage, use the staging label.

      GET: /secretsmanager/get?secretId=secretId&versionStage=AWSPREVIOUS
    • To retrieve a specific secret version by ID, for secretId, use the ARN or name of the secret, and for versionId, use the version ID.

      GET: /secretsmanager/get?secretId=secretId&versionId=versionId
    Example Retrieve a secret (Python)

    The following Python example shows how to retrieve a secret and parse the result using json.loads.

    secrets_extension_endpoint = "http://localhost:" + \ secrets_extension_http_port + \ "/secretsmanager/get?secretId=" + \ <secret_name> r = requests.get(secrets_extension_endpoint, headers=headers) secret = json.loads(r.text)["SecretString"] # load the Secrets Manager response into a Python dictionary, access the secret

AWS Parameters and Secrets Lambda Extension environment variables

You can configure the extension with the following environment variables.

For information about how to use environment variables, see Using Lambda environment variables in the Lambda Developer Guide.

PARAMETERS_SECRETS_EXTENSION_CACHE_ENABLED

Set to true to cache parameters and secrets. Set to false for no caching. Default is true.

PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE

The maximum number of secrets and parameters to cache. Must be a value from 0 to 1000. A value of 0 means there is no caching. This variable is ignored if both SSM_PARAMETER_STORE _TTL and SECRETS_MANAGER_TTL are 0. Default is 1000.

PARAMETERS_SECRETS_EXTENSION_HTTP_PORT

The port for the local HTTP server. Default is 2773.

PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL

The level of logging the extension provides: debug, info, warn, error, or none. Set to debug to see the cache configuration. Default is info.

PARAMETERS_SECRETS_EXTENSION_MAX_CONNECTIONS

Maximum number of connections for HTTP clients that the extension uses to make requests to Parameter Store or Secrets Manager. This is a per-client configuration. Default is 3.

SECRETS_MANAGER_TIMEOUT_MILLIS

Timeout for requests to Secrets Manager in milliseconds. A value of 0 means there is no timeout. Default is 0.

SECRETS_MANAGER_TTL

TTL of a secret in the cache in seconds. A value of 0 means there is no caching. The maximum is 300 seconds. This variable is ignored if PARAMETERS_SECRETS_CACHE_SIZE is 0. Default is 300 seconds.

SSM_PARAMETER_STORE_TIMEOUT_MILLIS

Timeout for requests to Parameter Store in milliseconds. A value of 0 means there is no timeout. Default is 0.

SSM_PARAMETER_STORE_TTL

TTL of a parameter in the cache in seconds. A value of 0 means there is no caching. The maximum is 300 seconds. This variable is ignored if PARAMETERS_SECRETS_CACHE_SIZE is 0. Default is 300 seconds.