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. 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.
The extension makes requests to localhost port 2773. 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).
To use the AWS Parameters and Secrets Lambda Extension
-
Add the layer to your function by doing one of the following:
Open the AWS Lambda console at https://console.aws.amazon.com/lambda/
. -
Choose your function, choose Layers, and then choose Add a layer.
-
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.
aws lambda update-function-configuration \ --function-name my-function \ --layersLayerARN
-
Grant permissions to the Lambda execution role to be able to access secrets:
-
secretsmanager:GetSecretValuepermission for the secret. See Example: Permission to retrieve secret values. -
(Optional) If the secret is encrypted with a customer managed key instead of the AWS managed key
aws/secretsmanager, the execution role also needskms:Decryptpermission for the KMS key. -
You can use Attribute Based Access Control (ABAC) with the Lambda role to allow for more granular access to secrets in the account. For more information, see Example: Control access to secrets using tags and Example: Limit access to identities with tags that match secrets' tags.
-
-
Configure the cache with Lambda environment variables.
-
To retrieve secrets from the extension cache, you first need to add the
X-AWS-Parameters-Secrets-Tokento the request header. Set the token toAWS_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')} -
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 forversionStage, 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 forversionId, 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_SIZEThe 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 _TTLandSECRETS_MANAGER_TTLare 0. Default is 1000.PARAMETERS_SECRETS_EXTENSION_HTTP_PORTThe 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, ornone. Set todebugto see the cache configuration. Default isinfo. 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_SIZEis 0. Default is 300 seconds. SSM_PARAMETER_STORE_TIMEOUT_MILLISTimeout for requests to Parameter Store in milliseconds. A value of 0 means there is no timeout. Default is 0.
SSM_PARAMETER_STORE_TTLTTL 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_SIZEis 0. Default is 300 seconds.
AWS Parameters and Secrets Lambda Extension ARNs
| Region | ARN |
|---|---|
|
US East (N. Virginia) |
|
|
US East (Ohio) |
|
|
US West (N. California) |
|
|
US West (Oregon) |
|
|
Canada (Central) |
|
|
Europe (Frankfurt) |
|
|
Europe (Zurich) |
|
|
Europe (Ireland) |
|
|
Europe (London) |
|
|
Europe (Paris) |
|
|
Europe (Stockholm) |
|
|
Europe (Milan) |
|
|
Europe (Spain) |
|
| China (Beijing) |
|
| China (Ningxia) |
|
|
Asia Pacific (Hong Kong) |
|
|
Asia Pacific (Hyderabad) |
|
|
Asia Pacific (Tokyo) |
|
| Asia Pacific (Osaka) |
|
|
Asia Pacific (Seoul) |
|
|
Asia Pacific (Singapore) |
|
|
Asia Pacific (Sydney) |
|
|
Asia Pacific (Jakarta) |
|
|
Asia Pacific (Mumbai) |
|
|
South America (São Paulo) |
|
|
Africa (Cape Town) |
|
| Middle East (UAE) | arn:aws:lambda:me-central-1:858974508948:layer:AWS-Parameters-and-Secrets-Lambda-Extension:4 |
|
Middle East (Bahrain) |
|
| AWS GovCloud (US-East) |
|
| AWS GovCloud (US-West) |
|
