{"id":2398,"library":"aws-secretsmanager-caching","title":"AWS Secrets Manager Caching","description":"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.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-secretsmanager-caching-python","tags":["aws","secretsmanager","caching","security","cloud"],"install":[{"cmd":"pip install aws-secretsmanager-caching","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for underlying AWS SDK client interactions with Secrets Manager.","package":"botocore","optional":false}],"imports":[{"note":"The primary class for managing the secret cache is available directly from the top-level package.","wrong":"from aws_secretsmanager_caching.secret_cache import SecretCache","symbol":"SecretCache","correct":"from aws_secretsmanager_caching import SecretCache"},{"symbol":"SecretCacheConfig","correct":"from aws_secretsmanager_caching import SecretCacheConfig"}],"quickstart":{"code":"import os\nimport boto3\nfrom aws_secretsmanager_caching import SecretCache, SecretCacheConfig\n\n# Configure cache (optional, default values are usually good)\ncache_config = SecretCacheConfig(\n    max_cache_size=100,\n    cache_item_ttl_in_milliseconds=3600000, # 1 hour\n    stall_time_in_milliseconds=1000 # 1 second\n)\n\n# Initialize a Secrets Manager client (optional, can be passed to SecretCache)\n# Ensure AWS credentials and region are configured via env vars or boto3 config\nsecrets_client = boto3.client(\n    'secretsmanager',\n    region_name=os.environ.get('AWS_REGION', 'us-east-1')\n)\n\n# Initialize the cache\ncache = SecretCache(client=secrets_client, config=cache_config)\n\n# Retrieve a secret\ntry:\n    secret_name = os.environ.get('MY_SECRET_NAME', 'my-test-secret')\n    secret_value = cache.get_secret_string(secret_name)\n    print(f\"Retrieved secret '{secret_name}': {secret_value}\")\n\n    # Subsequent calls will hit the cache until TTL expires\n    secret_value_cached = cache.get_secret_string(secret_name)\n    print(f\"Retrieved secret (cached) '{secret_name}': {secret_value_cached}\")\n\nexcept Exception as e:\n    print(f\"Error retrieving secret: {e}\")\n\nfinally:\n    # It's good practice to close the cache when done, especially in short-lived processes\n    cache.close()","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"1.1.3 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}