diff --git a/website/content/docs/agent/caching.mdx b/website/content/docs/agent/caching/index.mdx similarity index 78% rename from website/content/docs/agent/caching.mdx rename to website/content/docs/agent/caching/index.mdx index 0651855b4afd..8c155dbddfc0 100644 --- a/website/content/docs/agent/caching.mdx +++ b/website/content/docs/agent/caching/index.mdx @@ -56,6 +56,30 @@ overrides the default behavior described above in [Using Auth-Auth Token](/docs/agent/caching#using-auto-auth-token), and instead ignores any existing Vault token in the request and instead uses the auto-auth token. +## Persistent Cache + +Vault Agent can restore tokens and leases from a persistent cache file created by a previous +Vault Agent process. The persistent cache is a BoltDB file that includes tuples encrypted +by a generated encryption key. The encrypted tuples include the Vault token used to retrieve +secrets, leases for tokens/secrets, and secret values. + +-> **Note:** Vault Agent Caching persistent cache will only restore _leased_ secrets. Secrets +that are not renewable, such as KV v2, will not be persisted. + +In order to use Vault Agent persistent cache, auto-auth must be used. During the restoration +of the cache, Vault Agent will pre-populate auto-auth with the persisted token. This token +is required to renew restored leases. If the token has expired, the cached leases will be evicted and +secrets will need to be retrieved from Vault. + +If Vault Agent templating is enabled alongside of the persistent cache, Vault Agent will automatically +route templating requests through the cache. This ensures template requests are cached and restored properly. + +At the time of this writing, Vault Agent persistent cache is only supported in a Kubernetes +environment. In the future the persistent cache will be expanded to include other environments. + +For more information about the Vault Agent persistent cache, see the sidebar for specific persistent +cache types. + ## Cache Evictions The eviction of cache entries pertaining to secrets will occur when the agent @@ -174,6 +198,25 @@ The top level `cache` block has the following configuration entries: forward the request to the Vault server. If set to `"force"` Agent will use the auto-auth token, overwriting the attached Vault token if set. +- `persist` `(object: optional)` - Configuration for the persistent cache. + +### Configuration (Persist) + +These are common configuration values that live within the `persist` block: + +- `type` `(string: required)` - The type of the persistent cahce to use, + e.g. `kubernetes`. _Note_: when using HCL this can be used as the key for + the block, e.g. `persist "kubernetes" {...}`. + +- `path` `(string: required)` - The path on disk where the persistent cache file + should be created or restored from. + +- `keep_after_import` `(bool: optional)` - When set to true, a restored cache file + is not deleted. Defaults to `false`. + +- `exit_on_err` `(bool: optional)` - When set to true, if any errors occur during + a persitent cache restore, Vault Agent will exit with an error. Defaults to `true`. + ## Configuration (`listener`) - `listener` `(array of objects: required)` - Configuration for the listeners. @@ -240,6 +283,42 @@ vault { } ``` +### Persistent Cache Example Configuration + +An example configuration, with very contrived values, follows: + +```javascript +auto_auth { + method "kubernetes" { + config = { + role = "foobar" + } + } + + sink "file" { + config = { + path = "/tmp/file-foo" + } + } +} + +cache { + use_auto_auth_token = true + persist "kubernetes" { + path = "/vault/agent-cache" + } +} + +listener "tcp" { + address = "127.0.0.1:8200" + tls_disable = true +} + +vault { + address = "http://127.0.0.1:8200" +} +``` + ## Learn Refer to the [Vault Agent diff --git a/website/content/docs/agent/caching/persistent-caches/index.mdx b/website/content/docs/agent/caching/persistent-caches/index.mdx new file mode 100644 index 000000000000..a8d1863c3db4 --- /dev/null +++ b/website/content/docs/agent/caching/persistent-caches/index.mdx @@ -0,0 +1,9 @@ +--- +layout: docs +page_title: Vault Agent Persistent Cache Types +description: Persistent Cache Types for Vault Agent Caching +--- + +# Vault Agent Persistent Cache Types + +Please see the sidebar for available types and their usage/configuration. diff --git a/website/content/docs/agent/caching/persistent-caches/kubernetes.mdx b/website/content/docs/agent/caching/persistent-caches/kubernetes.mdx new file mode 100644 index 000000000000..5217edb06d8e --- /dev/null +++ b/website/content/docs/agent/caching/persistent-caches/kubernetes.mdx @@ -0,0 +1,25 @@ +--- +layout: docs +page_title: Kubernetes - Vault Agent Persistent Cache +description: Kubernetes Persistent Cache for Vault Agent Caching +--- + +# Vault Agent Kubernetes Persistent Cache + +When `kubernetes` is configured for the persistent cache type, Vault Agent will optimize the +persistent cache specifically for Kubernetes. This type of persistent cache requires a Kubernetes +service account token. The service account token is used during encryption and decryption of the +persistent cache as an additional integrity check. + +The Vault Agent persistent cache file in Kubernetes should only be used for handing off Vault tokens +and leases between initialization and sidecar Vault Agent containers. This cache file should be shared +using a memory volume between the Vault Agent containers. + +If the Vault Agent Injector for Kubernetes is being used, the persistent cache is automatically configured +and used if the annotation [`vault.hashicorp.com/agent-cache-enable: true`](/docs/platform/k8s/injector/annotations#vault-hashicorp-com-agent-cache-enable) is set. + +## Configuration + +- `service_account_token_file` `(string: optional)` - When type is set to `kubernetes`, + this configures the path on disk where the Kubernetes service account token can be found. + Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1697a2f90297..44b05b7b05c2 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -765,7 +765,25 @@ }, { "title": "Caching", - "path": "agent/caching" + "routes": [ + { + "title": "Overview", + "path": "agent/caching" + }, + { + "title": "Persistent Caching", + "routes": [ + { + "title": "Overview", + "path": "agent/caching/persistent-caches" + }, + { + "title": "Kubernetes", + "path": "agent/caching/persistent-caches/kubernetes" + } + ] + } + ] }, { "title": "Templates",