Registry / aws / aws-secretsmanager-caching

aws-secretsmanager-caching

JSON →
library1.1.3pypypi✓ verified 24d ago

The `aws-secretsmanager-caching` library provides a client-side caching solution for AWS Secrets Manager. It helps reduce API calls to Secrets Manager, improving application performance and potentially lowering costs, by storing secret values in memory for a configurable duration. The current version is 1.1.3 and it is actively maintained by AWS.

pip install aws-secretsmanager-caching
INSTALL
IMPORT
SIG · AWS-SECRETSMANAGER
A
aws-secretsmanager-caching
awspythonv1.1.3
Install
3.0s avg
Import
517ms
Disk
48MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.526s · 49.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.0s · import 0.508s · 50MB
48MB installed
● package 48MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SecretCache
from aws_secretsmanager_caching import SecretCache
from aws_secretsmanager_caching.secret_cache import SecretCache
The primary class for managing the secret cache is available directly from the top-level package.
SecretCacheConfig
from aws_secretsmanager_caching import SecretCacheConfig

This quickstart demonstrates how to initialize `SecretCache` with optional configuration, retrieve a secret, and observe the caching behavior. Ensure your AWS credentials and region are configured (e.g., via environment variables or AWS CLI configuration) for `boto3` to work correctly. The `os.environ.get` calls are for demonstration purposes; replace `'my-test-secret'` with an actual secret name.

import os import boto3 from aws_secretsmanager_caching import SecretCache, SecretCacheConfig # Configure cache (optional, default values are usually good) cache_config = SecretCacheConfig( max_cache_size=100, cache_item_ttl_in_milliseconds=3600000, # 1 hour stall_time_in_milliseconds=1000 # 1 second ) # Initialize a Secrets Manager client (optional, can be passed to SecretCache) # Ensure AWS credentials and region are configured via env vars or boto3 config secrets_client = boto3.client( 'secretsmanager', region_name=os.environ.get('AWS_REGION', 'us-east-1') ) # Initialize the cache cache = SecretCache(client=secrets_client, config=cache_config) # Retrieve a secret try: secret_name = os.environ.get('MY_SECRET_NAME', 'my-test-secret') secret_value = cache.get_secret_string(secret_name) print(f"Retrieved secret '{secret_name}': {secret_value}") # Subsequent calls will hit the cache until TTL expires secret_value_cached = cache.get_secret_string(secret_name) print(f"Retrieved secret (cached) '{secret_name}': {secret_value_cached}") except Exception as e: print(f"Error retrieving secret: {e}") finally: # It's good practice to close the cache when done, especially in short-lived processes cache.close()
Debug
Known issues
gotchaMisconfiguring `cache_item_ttl_in_milliseconds` or `stall_time_in_milliseconds` can lead to stale secrets being served or excessive API calls. `stall_time_in_milliseconds` allows the cache to return a stale value while attempting to refresh it in the background.
fix
Carefully consider your application's tolerance for stale data versus API call frequency. For rapidly changing secrets, use a lower TTL. For critical secrets where staleness is unacceptable, you might need to rely on `refreshNow()` or avoid aggressive caching. Understand the difference between `ttl` and `stall_time` in `SecretCacheConfig`.
affects: All versions
gotchaEnsure the underlying `boto3` Secrets Manager client (or the default client used by the cache) is configured for the correct AWS region and possesses the necessary IAM permissions to access secrets.
fix
Explicitly pass a `boto3` Secrets Manager client to `SecretCache(client=...)` that is initialized with the desired region. Verify the IAM role/user credentials have `secretsmanager:GetSecretValue` permissions for the target secrets.
affects: All versions
breakingVersion 1.1.3 updated internal dependency resolution from `pkg_resources` to `importlib.metadata`. While not directly affecting public API, environments relying on specific `pkg_resources` behavior or with very old `setuptools` installations might encounter issues if they have complex dependency trees.
fix
Upgrade `setuptools` to a recent version if encountering import or distribution issues related to metadata. For most users, this change is internal and will not require action, but it's a good practice to test thoroughly after upgrading.
affects: 1.1.3 and later
gotchaThe cache is in-memory and not shared across processes or instances. Each application instance will maintain its own cache. When deploying, consider the impact on cold starts and initial secret fetches for new instances.
fix
This is expected behavior. If shared caching is required, an external caching layer (e.g., Redis) would be necessary, but this library is specifically for client-side in-memory caching. Design your application's scaling to account for individual cache warm-up.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aws_secretsmanager_caching'
The 'aws-secretsmanager-caching' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install aws-secretsmanager-caching'.
botocore.exceptions.ClientError: An error occurred (AccessDeniedException) when calling the GetSecretValue operation: User is not authorized to perform: secretsmanager:GetSecretValue
The IAM user or role lacks the necessary permissions to retrieve the secret from AWS Secrets Manager.
fix
Ensure the IAM policy attached to the user or role includes 'secretsmanager:GetSecretValue' permission.
botocore.exceptions.ClientError: An error occurred (ResourceNotFoundException) when calling the GetSecretValue operation: Secrets Manager can't find the specified secret.
The specified secret name or ARN does not exist in AWS Secrets Manager.
fix
Verify the secret name or ARN is correct and that the secret exists in the specified AWS region.
TypeError: __init__() got an unexpected keyword argument 'config'
Incorrect instantiation of the SecretCache class with an invalid keyword argument.
fix
Initialize the SecretCache class with the correct parameters: 'cache = SecretCache(config=cache_config, client=client)'.
botocore.exceptions.NoCredentialsError: Unable to locate credentials
AWS credentials are not configured or accessible in the environment.
fix
Configure AWS credentials using the AWS CLI with 'aws configure' or set environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
Upgrade
Version history
1.1.3latest on PyPI · released Jun 20, 2024
Audit
Dependencies
botocorerequiredRequired for underlying AWS SDK client interactions with Secrets Manager.
Agent activity
16 hits · last 30 days
node
14
Resources
aws-secretsmanager-caching — pip install aws-secretsmanager-caching · libregistry