AWS secretsmanager documentation change
Summary
Restructured documentation to focus on Lambda integration, removed technical implementation details, and added references to Lambda Developer Guide. Deleted environment variable configurations and code examples while adding VPC endpoint guidance.
Security assessment
The changes emphasize security best practices like VPC endpoint configuration and permission requirements, but do not address a specific disclosed vulnerability. Security documentation is added through references to IAM permissions and network isolation controls.
Diff
diff --git a/secretsmanager/latest/userguide/retrieving-secrets_lambda.md b/secretsmanager/latest/userguide/retrieving-secrets_lambda.md index ab602b414..fd77b6b15 100644 --- a//secretsmanager/latest/userguide/retrieving-secrets_lambda.md +++ b//secretsmanager/latest/userguide/retrieving-secrets_lambda.md @@ -5 +5 @@ -Environment variables +Get secrets with LambdaParameter Store integration @@ -9 +9 @@ Environment variables -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](https://docs.aws.amazon.com/systems-manager/latest/userguide/ps-integration-lambda-extensions.html) in the _AWS Systems Manager User Guide_. +AWS Lambda is a serverless compute service that lets you run code without provisioning or managing servers. Parameter Store, a capability of AWS Systems Manager, provides secure, hierarchical storage for configuration data management and secrets management. You can use the AWS Parameters and Secrets Lambda Extension to retrieve and cache AWS Secrets Manager secrets and Parameter Store parameters in Lambda functions without using an SDK. For detailed information about using this extension, see [Use Secrets Manager secrets in Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/with-secrets-manager.html) in the _Lambda Developer Guide_. @@ -11 +11 @@ You can use the AWS Parameters and Secrets Lambda Extension to retrieve and cach -A Lambda extension is a companion process that adds to the capabilities of a Lambda function. For more information, see [Lambda extensions](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-extensions-api.html) 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 ](https://aws.amazon.com/blogs/compute/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`. +## Using Secrets Manager secrets with Lambda @@ -13 +13 @@ A Lambda extension is a companion process that adds to the capabilities of a Lam -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`. +The Lambda Developer Guide provides comprehensive instructions for using Secrets Manager secrets in Lambda functions. To get started: @@ -15 +15 @@ To provide the in-memory cache for parameters and secrets, the extension exposes -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](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html) in the _Lambda Developer Guide_. + 1. Follow the step-by-step tutorial in [Use Secrets Manager secrets in Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/with-secrets-manager.html), which includes: @@ -17 +17 @@ Lambda instantiates separate instances corresponding to the concurrency level th -To add the extension for ARM, you must use the `arm64` architecture for your Lambda function. For more information, see [Lambda instruction set architectures](https://docs.aws.amazon.com/lambda/latest/dg/foundation-arch.html) 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). + * Creating a Lambda function with your preferred runtime (Python, Node.js, Java) @@ -19 +19 @@ To add the extension for ARM, you must use the `arm64` architecture for your Lam -The extension uses an AWS client. For information about configuring the AWS client, see [Settings reference](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html) 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](./vpc-endpoint-overview.html). + * Adding the AWS Parameters and Secrets Lambda Extension as a layer @@ -21 +21 @@ The extension uses an AWS client. For information about configuring the AWS clie -**Required permissions:** + * Configuring the necessary permissions @@ -23 +23 @@ The extension uses an AWS client. For information about configuring the AWS clie - * The Lambda [execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) must have `secretsmanager:GetSecretValue` permission to the secret. + * Writing code to retrieve secrets from the extension @@ -25 +25 @@ The extension uses an AWS client. For information about configuring the AWS clie - * If the secret is encrypted with a customer managed key instead of the AWS managed key `aws/secretsmanager`, the execution role also needs `kms:Decrypt` permission for the KMS key. + * Testing your function @@ -26,0 +27 @@ The extension uses an AWS client. For information about configuring the AWS clie + 2. Learn about environment variables for configuring the extension's behavior, including cache settings and timeouts @@ -27,0 +29 @@ The extension uses an AWS client. For information about configuring the AWS clie + 3. Understand best practices for working with secret rotation @@ -30 +31,0 @@ The extension uses an AWS client. For information about configuring the AWS clie -###### To use the AWS Parameters and Secrets Lambda Extension @@ -32 +32,0 @@ The extension uses an AWS client. For information about configuring the AWS clie - 1. Add the **AWS layer** named **AWS Parameters and Secrets Lambda Extension** to your function. For instructions, see [Adding layers to functions ](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) in the _Lambda Developer Guide_. If you use the AWS CLI to add the layer, you need the ARN of the extension. For a list of ARNs, see [AWS Parameters and Secrets Lambda Extension ARNs](https://docs.aws.amazon.com/systems-manager/latest/userguide/ps-integration-lambda-extensions.html#ps-integration-lambda-extensions-add) in the _AWS Systems Manager User Guide_. @@ -34 +34 @@ The extension uses an AWS client. For information about configuring the AWS clie - 2. Grant permissions to the Lambda [execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) to be able to access secrets: +### Using Secrets Manager and Lambda in a VPC @@ -36 +36 @@ The extension uses an AWS client. For information about configuring the AWS clie - * `secretsmanager:GetSecretValue` permission for the secret. See [Example: Permission to retrieve individual secret values](./auth-and-access_resource-policies.html#auth-and-access_examples_read). +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](./vpc-endpoint-overview.html). @@ -38 +38 @@ The extension uses an AWS client. For information about configuring the AWS clie - * (Optional) If the secret is encrypted with a customer managed key instead of the AWS managed key `aws/secretsmanager`, the execution role also needs `kms:Decrypt` permission for the KMS key. +## Using the AWS Parameters and Secrets Lambda Extension @@ -40 +40 @@ The extension uses an AWS client. For information about configuring the AWS clie - * 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 [Control access to secrets using attribute-based access control (ABAC)](./auth-and-access-abac.html). +The extension can retrieve both Secrets Manager secrets and Parameter Store parameters. For detailed information about using Parameter Store parameters with the extension, see [Using Parameter Store parameters in Lambda functions](https://docs.aws.amazon.com/systems-manager/latest/userguide/ps-integration-lambda-extensions.html) in the _AWS Systems Manager User Guide_. @@ -42 +42 @@ The extension uses an AWS client. For information about configuring the AWS clie - 3. Configure the cache with Lambda environment variables. +The Systems Manager documentation includes: @@ -44 +44 @@ The extension uses an AWS client. For information about configuring the AWS clie - 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. + * Detailed explanation of how the extension works with Parameter Store @@ -46 +46 @@ The extension uses an AWS client. For information about configuring the AWS clie -The following Python example shows how to add the header. + * Instructions for adding the extension to a Lambda function @@ -48,2 +48 @@ The following Python example shows how to add the header. - import os - headers = {"X-Aws-Parameters-Secrets-Token": os.environ.get('AWS_SESSION_TOKEN')} + * Environment variables for configuring the extension @@ -51 +50 @@ The following Python example shows how to add the header. - 5. To retrieve a secret within the Lambda function, use one of the following HTTP GET requests: + * Sample commands for retrieving parameters @@ -53 +52 @@ The following Python example shows how to add the header. - * To retrieve a secret, for `secretId`, use the ARN or name of the secret. + * Complete list of extension ARNs for all supported architectures and regions @@ -55 +53,0 @@ The following Python example shows how to add the header. - GET: /secretsmanager/get?secretId=secretId @@ -57 +54,0 @@ The following Python example shows how to add the header. - * 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. @@ -59,72 +55,0 @@ The following Python example shows how to add the header. - 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`](https://docs.python.org/3/library/json.html). - - 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](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html) 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_EXTENSION_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_EXTENSION_CACHE_SIZE` is 0. Default is 300 seconds.