AWS Secrets Manager Caching

Warnings

• gotcha Misconfiguring `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`.
• gotcha Ensure 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.
• breaking Version 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.
• gotcha The 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.

Install

• pip install aws-secretsmanager-caching Install stable version

Imports

• SecretCache

  from aws_secretsmanager_caching 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

Quickstart

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()