Metadata cache
Learn how Vault caches structural information and metadata
Vault maintains an in-memory cached copy of your collection schemas, IAM, and other configurations to speed up data access. When running Vault in multiple containers, the cache's behavior may affect certain Vault features. This page explains these impacts.
What is cached?
Vault caches structural and metadata information for data operations. This information includes:
- Collection names
- Details of all properties within a collection
- Encryption keys for encrypted properties
- The IAM configuration
- The environment variables
Your data and the Control operations are never cached.
Cache refresh rate
By default, the cache is refreshed every 30 seconds, which is suitable for most use cases. You can modify this setting with the PVAULT_SERVICE_CACHE_REFRESH_INTERVAL environment variable. When this environment variable is set to zero, the cache is turned off. Turning off the cache in production systems is not recommended.
What's the impact?
There is no impact on environments with one container, such as a local development environment. For production environments with multiple containers, metadata changes follow the semantic of eventual consistency.
When making "breaking" changes to a schema, allow the cache refresh period for Vault to propagate the changes to all instances. Only then can you perform normal data operations that depend on the changes.
Alternatively, you can force a cache reload to ensure a data operation has the latest schema details.
Forcing a cache reload
To reload the cache before accessing an object, use:
- CLI – use
--reload-cache - REST API – use
reload_cache=trueon the call.
This reloads the cache in the instance where the call was made; the caches on other instances are not updated. Take an example where you have three instances: a change is made on the first, and a force reload is performed on the second. The thirty remain out-of-date until it is either force reloaded or the automatic refresh occurs.