scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-04 04:28:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

VAULT-19278 Static secret caching docs (#23621)

Browse Source 
* VAULT-19278 First draft of static secret caching docs

* VAULT-19278 Add warning to Agent docs, fix capitalization

* VAULT-19278 typos/formatting

* VAULT-19278 changelog

* VAULT-19278 update based on PR feedback

* VAULT-19278 review feedback

* VAULT-19278 Update based on review

* VAULT-19278 update based on PR feedback

* VAULT-19278 incorporate a lot of PR feedback

* VAULT-19278 Rest of the suggestions

* VAULT-19278 I missed a suggestion

* VAULT-19278 More updates

* VAULT-19278 add docs for disable dynamic secret caching

* VAULT-19278 update changelog

* VAULT-19278 update based on comments
This commit is contained in:
Violet Hynes
2023-11-02 16:01:49 -04:00
committed by GitHub
parent eb9272d266
commit 1c9090b117
17 changed files with 317 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
changelog/23621.txt Normal file
View File

@@ -0,0 +1,3 @@
```release-note:feature
**Vault Proxy Static Secret Caching**: Adds support for static secret (KVv1 and KVv2) caching to Vault Proxy.
```

12
website/content/docs/agent-and-proxy/agent/apiproxy.mdx
View File

@@ -6,7 +6,7 @@ description: >-
for Vault's API. for Vault's API.
--- ---
# Vault agent API proxy # Vault Agent API proxy
Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
for Vault's API. for Vault's API.
@@ -14,6 +14,16 @@ for Vault's API.
~> Note: This functionality will be deprecated in a future release. Please ~> Note: This functionality will be deprecated in a future release. Please
switch to using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API proxying purposes, instead. switch to using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API proxying purposes, instead.
<Note title="Use Vault Proxy for static secret caching">
[Static secret caching](/vault/docs/agent-and-proxy/proxy/caching/static-secret-caching)
(KVv1 and KVv2) with API proxy minimizes the number of requests forwarded to
Vault. Vault Agent does not support static secret caching with API proxy. We
recommend using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API Proxy
related workflows.
</Note>
## Functionality ## Functionality
The [`listener` stanza](/vault/docs/agent-and-proxy/agent#listener-stanza) for Vault Agent configures a listener for Vault Agent. If The [`listener` stanza](/vault/docs/agent-and-proxy/agent#listener-stanza) for Vault Agent configures a listener for Vault Agent. If

19
website/content/docs/agent-and-proxy/agent/caching/index.mdx
View File

@@ -7,18 +7,23 @@ description: |-
newly created tokens. newly created tokens.
--- ---
# Vault agent caching # Vault Agent caching
<Note title="Use Vault Proxy for static secret caching">
[Static secret caching](/vault/docs/agent-and-proxy/proxy/caching/static-secret-caching)
(KVv1 and KVv2) with API proxy minimizes the number of requests forwarded to
Vault. Vault Agent does not support static secret caching with API proxy. We
recommend using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API Proxy
related workflows.
</Note>
Vault Agent Caching allows client-side caching of responses containing newly Vault Agent Caching allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these created tokens and responses containing leased secrets generated off of these
newly created tokens. The renewals of the cached tokens and leases are also newly created tokens. The renewals of the cached tokens and leases are also
managed by the agent. managed by the agent.
-> **Note:** Vault Agent Caching works best with servers/clusters that are
running on Vault 1.1 and above due to changes that were introduced
alongside this feature, such as the exposure of the `orphan` field in token
creation responses.
## Caching and renewals ## Caching and renewals
Response caching and renewals are managed by the agent only under these Response caching and renewals are managed by the agent only under these
@@ -68,7 +73,7 @@ entries based on some of the query criteria used for indexing the cache entries.
## Request uniqueness ## Request uniqueness
In order to detect repeat requests and return cached responses, agent will need In order to detect repeat requests and return cached responses, Agent needs
to have a way to uniquely identify the requests. This computation as it stands to have a way to uniquely identify the requests. This computation as it stands
today takes a simplistic approach (may change in future) of serializing and today takes a simplistic approach (may change in future) of serializing and
hashing the HTTP request along with all the headers and the request body. This hashing the HTTP request along with all the headers and the request body. This

2
website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx
View File

@@ -4,7 +4,7 @@ page_title: Vault Agent Persistent Caching
description: Vault Agent Caching description: Vault Agent Caching
--- ---
# Vault agent persistent caching # Vault Agent persistent caching
Vault Agent can restore tokens and leases from a persistent cache file created 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 by a previous Vault Agent process. The persistent cache is a BoltDB file that

2
website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx
View File

@@ -4,7 +4,7 @@ page_title: Kubernetes - Vault Agent Persistent Cache
description: Kubernetes Persistent Cache for Vault Agent Caching description: Kubernetes Persistent Cache for Vault Agent Caching
--- ---
# Vault agent kubernetes persistent cache # Vault Agent Kubernetes persistent cache
When `kubernetes` is configured for the persistent cache type, Vault Agent will optimize the 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 persistent cache specifically for Kubernetes. This type of persistent cache requires a Kubernetes

2
website/content/docs/agent-and-proxy/agent/process-supervisor.mdx
View File

@@ -6,7 +6,7 @@ description: >-
into a process via environment variables using Consul Template markup. into a process via environment variables using Consul Template markup.
--- ---
# Vault agent's process supervisor mode # Vault Agent's Process Supervisor mode
Vault Agent's Process Supervisor Mode allows Vault secrets to be injected into Vault Agent's Process Supervisor Mode allows Vault secrets to be injected into
a process via environment variables using a process via environment variables using

2
website/content/docs/agent-and-proxy/agent/template.mdx
View File

@@ -6,7 +6,7 @@ description: >-
files using Consul Template markup. files using Consul Template markup.
--- ---
# Vault agent templates # Vault Agent templates
Vault Agent's Template functionality allows Vault secrets to be rendered to files Vault Agent's Template functionality allows Vault secrets to be rendered to files
or environment variables (via the [Process Supervisor Mode](/vault/docs/agent-and-proxy/agent/process-supervisor)) or environment variables (via the [Process Supervisor Mode](/vault/docs/agent-and-proxy/agent/process-supervisor))

43
website/content/docs/agent-and-proxy/agent/versions.mdx
View File

@@ -2,21 +2,30 @@
layout: docs layout: docs
page_title: Vault Agent Version Compatibility page_title: Vault Agent Version Compatibility
description: |- description: |-
Guidelines for running different versions of Agent and Server Guidelines for running different versions of Agent and Vault server
--- ---
# Running different versions of agent and server # Running different versions of Agent and Vault server
There is no requirement to run identical versions of Vault Agent and Vault Server. There is no requirement to run identical versions of Vault Agent and Vault server.
It is safe to run different versions, however you may not be able to take advantage of all the newest features in Vault if you do not upgrade to the most recent versions of Agent and Server. We recognize that this isn’t always possible, so we do support version mismatch as best as possible. It is safe to run different versions. However, you may not be able to take
advantage of all the newest features in Vault if you do not upgrade to
the most recent versions of Agent and Vault server.
As of Vault Agent 1.13.0, Agent will write a note to its logs when it detects a mismatch between Agent and Server. This is purely informative, intended to assist with debugging in case the mismatch is given rise to problems, e.g. because a newer Agent version is trying to make use of functionality that doesn't exist in the Server version it's talking to. If Agent is behaving acceptably, the message may be ignored. The Agent writes a note to the logs when it detects a mismatch between
Agent and Vault server versions. The note is purely informative to assist
with debugging when the problem may be related to a version mismatch.
For example, when a newer Agent version expects functionality that is
not available in an older version of Vault.
This document describes the common cases. There may be occasional exceptions, which if intentional will be called out in the CHANGELOG in a `CHANGES` section. If unintentional/undocumented these should be treated as bugs and reported. This document describes the common cases. There may be occasional exceptions, which if intentional will be called out in the CHANGELOG in a `CHANGES` section. If unintentional/undocumented these should be treated as bugs and reported.
## Older version of agent than server ## When Vault Agent is older
We do not anticipate any problems stemming from continuing to run an older Agent version after the server nodes are upgraded to a later version. Existing deployments using Agent should not be impacted, as we don't generally make backwards-incompatible changes to Vault Server. In most cases, Vault server upgrades are backwards compatible with
older versions of Vault Agent. In the rare case where a Vault upgrade is
**not** backwards compatible, we document the relevant information in
the Vault upgrade guide.
Auto-auth: Auto-auth:
- new auth methods that have been introduced since Agent was built will be unavailable - new auth methods that have been introduced since Agent was built will be unavailable
@@ -29,19 +38,27 @@ Templating:
- the templating language features that interact with the Vault server use stable Vault APIs to retrieve and renew secrets - the templating language features that interact with the Vault server use stable Vault APIs to retrieve and renew secrets
- even if new secret engine types are introduced in newer Vault releases, these should not require an Agent upgrade to access via templates - even if new secret engine types are introduced in newer Vault releases, these should not require an Agent upgrade to access via templates
## Newer version of agent than server ## When Vault Agent is newer
It is possible that an Agent could depend on features that don’t exist in older Server versions. Newer Vault Agent versions will not work with older versions of Vault if
the Agent depends on features that do not exist in older Vault server
versions. Whenever possible, we release newer functionality as opt-in
and provide graceful degradation when connecting to an older Vault
server instance. But the new functionality may be required in cases
where the change relates unless there's a very good reason (such as a
serious security flaw being patched)
Auto-auth: Auto-auth:
- Agent may claim to support newer auth methods that have been introduced since Server was built, but they won't work due to Server not supporting them - Agent may support authentication methods that are unavailable in older versions of Vault.
- Agent may make use of new functionality for existing auth methods that isn't available in an older Server you're using - Agent may make use of newer functionality for existing authentication methods.
- Generally we will try to make such a change be opt-in, or to gracefully degrade when connecting to an older Server instance, unless there's a very good reason (such as a serious security flaw being patched)
Proxy: Proxy:
- since Agent simply mirrors the incoming requests, it is unlikely that incompatibilities would surface in proxying, but new functionality may not be available - since Agent simply mirrors the incoming requests, it is unlikely that incompatibilities would surface in proxying, but new functionality may not be available
- example: When client-controlled consistency support was added to Agent, it started looking for X-Vault-Index headers in responses, and started providing X-Vault-Index headers in proxied requests. Older Vault Enterprise servers that don't make use of these headers would ignore the new request header and not emit them either. Agent proxying behaviour continued unchanged, unable to take advantage of the new functionality, but also not impeded in its previously existing behavior. - example: When client-controlled consistency support was added to Agent, it started looking for X-Vault-Index headers in responses, and started providing X-Vault-Index headers in proxied requests. Older Vault Enterprise servers that don't make use of these headers would ignore the new request header and not emit them either. Agent proxying behaviour continued unchanged, unable to take advantage of the new functionality, but also not impeded in its previously existing behavior.
Templating: Templating:
- we don't anticipate a scenario where changes to Agent's templating itself gives rise to an incompatibility with older Vault Servers, though of course with any Agent version it's possible to write templates that issue requests which make use of functionality not yet present in the upstream vault server, e.g. {{ with secret "secret/my-secret?some-new-option" }} - We do not anticipate incompatibility between Agent templating and
older Vault servers. However, it is possible to write templates that
makes request for functionality not available in the upstream Vault
server. For example, `{{ with secret "secret/my-secret?some-new-option" }}`
- we would not deliberately make a change to templating that breaks existing deployments - we would not deliberately make a change to templating that breaks existing deployments

10
website/content/docs/agent-and-proxy/agent/winsvc.mdx
View File

@@ -5,7 +5,7 @@ description: >-
Vault Agent can be run as a Windows service. Vault Agent can be run as a Windows service.
--- ---
# Vault agent windows service # Vault Agent Windows service
Vault Agent can be run as a Windows service. In order to do this, you need to register Vault Agent with the Windows Vault Agent can be run as a Windows service. In order to do this, you need to register Vault Agent with the Windows
Service Control Manager. After Vault Agent is registered, it can be started like any other Windows Service Control Manager. After Vault Agent is registered, it can be started like any other Windows
@@ -13,7 +13,7 @@ service.
**Note:** These commands should be run in a PowerShell session with Administrator capabilities. **Note:** These commands should be run in a PowerShell session with Administrator capabilities.
## Register Vault agent as a windows service ## Register Vault Agent as a Windows service
There are multiple ways to register Vault Agent as a Windows service. One way is to use There are multiple ways to register Vault Agent as a Windows service. One way is to use
[`sc.exe`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create). `sc.exe` works [`sc.exe`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create). `sc.exe` works
@@ -77,7 +77,7 @@ If anything goes wrong during this process, and you need to manually edit the pa
the following key: `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\VaultAgent`. You can edit the `ImagePath` value the following key: `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\VaultAgent`. You can edit the `ImagePath` value
at that key to the correct path. at that key to the correct path.
## Start the Vault agent service ## Start the Vault Agent service
There are multiple ways to start the service. There are multiple ways to start the service.
@@ -86,7 +86,7 @@ There are multiple ways to start the service.
- Go to the Windows Service Manager, and look for **VaultAgent** in the service name column. Click the - Go to the Windows Service Manager, and look for **VaultAgent** in the service name column. Click the
`Start` button to start the service. `Start` button to start the service.
### Example starting Vault agent using `sc.exe` ### Example starting Vault Agent using `sc.exe`
```shell-session ```shell-session
PS C:\Windows\system32> sc.exe start VaultAgent PS C:\Windows\system32> sc.exe start VaultAgent
@@ -103,7 +103,7 @@ SERVICE_NAME: VaultAgent
FLAGS : FLAGS :
``` ```
### Example starting Vault agent using `Start-Service` ### Example starting Vault Agent using `Start-Service`
```shell-session ```shell-session
PS C:\Windows\system32> Start-Service -Name "VaultAgent" PS C:\Windows\system32> Start-Service -Name "VaultAgent"

4
website/content/docs/agent-and-proxy/index.mdx
View File

@@ -6,7 +6,7 @@ description: |-
functionality automatically. functionality automatically.
--- ---
# Vault agent and Vault proxy # Vault Agent and Vault Proxy
A valid client token must accompany most requests to Vault. This A valid client token must accompany most requests to Vault. This
includes all API requests, as well as via the Vault CLI and other libraries. includes all API requests, as well as via the Vault CLI and other libraries.
@@ -76,7 +76,7 @@ to update and maintain the Vault integration code for every application. When
third party applications are being deployed by the application, it is prohibited third party applications are being deployed by the application, it is prohibited
to add the Vault integration code. to add the Vault integration code.
### Introduce Vault agent and Vault proxy to the workflow ### Introduce Vault Agent and Vault Proxy to the workflow
[Vault Agent][vaultagent] and [Vault Proxy][vaultproxy] aim to remove this initial hurdle to adopt Vault by providing a [Vault Agent][vaultagent] and [Vault Proxy][vaultproxy] aim to remove this initial hurdle to adopt Vault by providing a
more scalable and simpler way for applications to integrate with Vault. Vault Agent can more scalable and simpler way for applications to integrate with Vault. Vault Agent can

2
website/content/docs/agent-and-proxy/proxy/apiproxy.mdx
View File

@@ -6,7 +6,7 @@ description: >-
for Vault's API. for Vault's API.
--- ---
# Vault proxy API proxy # Vault Proxy API proxy
Vault Proxy's API Proxy functionality allows you to use Vault Proxy's API as a proxy Vault Proxy's API Proxy functionality allows you to use Vault Proxy's API as a proxy
for Vault's API. for Vault's API.

54
website/content/docs/agent-and-proxy/proxy/caching/index.mdx
View File

@@ -7,21 +7,17 @@ description: |-
newly created tokens. newly created tokens.
--- ---
# Vault proxy caching # Vault Proxy caching
Vault Proxy Caching allows client-side caching of responses containing newly Vault Proxy caching allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these created tokens and responses containing leased secrets generated off of these
newly created tokens. The renewals of the cached tokens and leases are also newly created tokens. The renewals of the cached tokens and leases are also
managed by the proxy. managed by the proxy. Additionally, with `cache_static_secrets` set to `true`,
Vault Proxy [can be configured to cache KVv1 and KVv2 secrets][static-secret-caching].
-> **Note:** Vault Proxy Caching works best with servers/clusters that are
running on Vault 1.1 and above due to changes that were introduced
alongside this feature, such as the exposure of the `orphan` field in token
creation responses.
## Caching and renewals ## Caching and renewals
Response caching and renewals are managed by the proxy only under these Response caching and renewals for dynamic secrets are managed by Proxy only under these
specific scenarios. specific scenarios.
1. Token creation requests are made through the proxy. This means that any 1. Token creation requests are made through the proxy. This means that any
@@ -36,10 +32,29 @@ specific scenarios.
that are issued using the tokens managed by the proxy, will be cached and that are issued using the tokens managed by the proxy, will be cached and
its renewals are taken care of. its renewals are taken care of.
## Static secret caching
You can configure Vault Proxy to cache dynamic secrets and static (KVv1 and KVv2)
secrets. When you enable caching for static secrets. Proxy keeps a cached entry
of the secret but only provides the cached response to requests made with tokens
that can access the secret. As a result, multiple requests to Vault Proxy for
the same KV secret only require a single, initial request to be forwarded to Vault.
Static secret caching is disabled by default. To enable caching for static secrets you must
configure [auto-auth](/vault/docs/agent-and-proxy/autoauth) and ensure the
auto-auth token has permission to subscribe to KV
[event](/vault/docs/concepts/events) updates.
Once configured, Proxy uses the auto-auth token to subscribe to KV events, and
monitors the subscription feed to know when to update the secrets in its cache.
For more information on static secret caching, refer to the
[Vault Proxy static secret caching][static-secret-caching] overview.
## Persistent cache ## Persistent cache
Vault Proxy can restore tokens and leases from a persistent cache file created Vault Proxy can restore secrets, such as, tokens, leases, and static secrets, from a persistent
by a previous Vault Proxy process. cache file created by a previous Vault Proxy process.
Refer to the [Vault Proxy Persistent Refer to the [Vault Proxy Persistent
Caching](/vault/docs/agent-and-proxy/proxy/caching/persistent-caches) page for more information on Caching](/vault/docs/agent-and-proxy/proxy/caching/persistent-caches) page for more information on
@@ -47,7 +62,7 @@ this functionality.
## Cache evictions ## Cache evictions
The eviction of cache entries pertaining to secrets will occur when the proxy The eviction of cache entries pertaining to dynamic secrets will occur when the proxy
can no longer renew them. This can happen when the secrets hit their maximum can no longer renew them. This can happen when the secrets hit their maximum
TTL or if the renewals result in errors. TTL or if the renewals result in errors.
@@ -68,7 +83,7 @@ entries based on some of the query criteria used for indexing the cache entries.
## Request uniqueness ## Request uniqueness
In order to detect repeat requests and return cached responses, proxy will need In order to detect repeat requests and return cached responses, Proxy needs
to have a way to uniquely identify the requests. This computation as it stands to have a way to uniquely identify the requests. This computation as it stands
today takes a simplistic approach (may change in future) of serializing and today takes a simplistic approach (may change in future) of serializing and
hashing the HTTP request along with all the headers and the request body. This hashing the HTTP request along with all the headers and the request body. This
@@ -150,10 +165,17 @@ $ curl \
## Configuration (`cache`) ## Configuration (`cache`)
The presence of the top level `cache` block in any way (including an empty `cache` block) will enable the cache. The presence of the top level `cache` block in any way (including an empty `cache` block) will enable the cache.
The top level `cache` block has the following configuration entry: Note that either `cache_static_secrets` must be `true` and/or `disable_caching_dynamic_secrets` must
be `false`, otherwise the cache does nothing. The top level `cache` block has the following configuration entries:
- `persist` `(object: optional)` - Configuration for the persistent cache. - `persist` `(object: optional)` - Configuration for the persistent cache.
- `cache_static_secrets` `(bool: false)` - Enables static secret caching when
`true`.
- `disable_caching_dynamic_secrets` `(bool: false)` - Disables dynamic secret caching when
`true`.
-> **Note:** When the `cache` block is defined, a [listener][proxy-listener] must also be defined -> **Note:** When the `cache` block is defined, a [listener][proxy-listener] must also be defined
in the config, otherwise there is no way to utilize the cache. in the config, otherwise there is no way to utilize the cache.
@@ -217,7 +239,7 @@ Here is an example of a cache configuration with the optional `persist` block,
alongside a regular listener, and a listener that only serves metrics. alongside a regular listener, and a listener that only serves metrics.
```hcl ```hcl
# Other Vault proxy configuration blocks # Other Vault Proxy configuration blocks
# ... # ...
cache { cache {
@@ -241,3 +263,5 @@ listener "tcp" {
role = "metrics_only" role = "metrics_only"
} }
``` ```
[static-secret-caching]: /vault/docs/agent-and-proxy/proxy/caching/static-secret-caching

9
website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/index.mdx
View File

@@ -4,7 +4,7 @@ page_title: Vault Proxy Persistent Caching
description: Vault Proxy Caching description: Vault Proxy Caching
--- ---
# Vault proxy persistent caching # Vault Proxy persistent caching
Vault Proxy can restore tokens and leases from a persistent cache file created Vault Proxy can restore tokens and leases from a persistent cache file created
by a previous Vault Proxy process. The persistent cache is a BoltDB file that by a previous Vault Proxy process. The persistent cache is a BoltDB file that
@@ -12,9 +12,6 @@ includes tuples encrypted by a generated encryption key. The encrypted tuples
include the Vault token used to retrieve secrets, leases for tokens/secrets, and include the Vault token used to retrieve secrets, leases for tokens/secrets, and
secret values. secret values.
-> **Note:** Vault Proxy Persistent Caching will only restore _leased_
secrets. Secrets that are not renewable, such as KV v2, will not be persisted.
In order to use Vault Proxy persistent cache, auto-auth must be used. If the In order to use Vault Proxy persistent cache, auto-auth must be used. If the
auto-auth token has expired by the time the cache is restored, the cache will auto-auth token has expired by the time the cache is restored, the cache will
be invalidated and secrets will need to be re-fetched from Vault. be invalidated and secrets will need to be re-fetched from Vault.
@@ -22,7 +19,7 @@ be invalidated and secrets will need to be re-fetched from Vault.
-> **Note** Vault Proxy persistent cache is currently supported only in a -> **Note** Vault Proxy persistent cache is currently supported only in a
Kubernetes environment. Kubernetes environment.
## Vault proxy persistent cache types ## Vault Proxy persistent cache types
Please see the sidebar for available types and their usage/configuration. Please see the sidebar for available types and their usage/configuration.
@@ -31,7 +28,7 @@ Please see the sidebar for available types and their usage/configuration.
Here is an example of a persistent cache configuration. Here is an example of a persistent cache configuration.
```hcl ```hcl
# Other Vault proxy configuration blocks # Other Vault Proxy configuration blocks
# ... # ...
cache { cache {

2
website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/kubernetes.mdx
View File

@@ -4,7 +4,7 @@ page_title: Kubernetes - Vault Proxy Persistent Cache
description: Kubernetes Persistent Cache for Vault Proxy Caching description: Kubernetes Persistent Cache for Vault Proxy Caching
--- ---
# Vault proxy kubernetes persistent cache # Vault Proxy kubernetes persistent cache
When `kubernetes` is configured for the persistent cache type, Vault Proxy will optimize the When `kubernetes` is configured for the persistent cache type, Vault Proxy will optimize the
persistent cache specifically for Kubernetes. This type of persistent cache requires a Kubernetes persistent cache specifically for Kubernetes. This type of persistent cache requires a Kubernetes

176
website/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx Normal file
View File

@@ -0,0 +1,176 @@
---
layout: docs
page_title: Vault Proxy Static Secret Caching
description: |-
Vault Proxy's static secret caching functionality allows you to cache KVv1 and KVv2 secrets for calling clients.
The secrets will be automatically updated by Proxy, minimizing requests made to Vault, and offering resiliency.
---
# Vault Proxy static secret caching
Use static secret caching with Vault Proxy to cache KVv1 and KVv2 secrets to
minimize requests made to Vault and provide resilient connections for clients.
## Step 1: Subscribe Vault Proxy to KV events
Vault Proxy uses Vault events and auto-auth to monitor secret status and make
appropriate cache updates.
1. Enable [auto-auth](/vault/docs/agent-and-proxy/autoauth).
1. Create an auto-auth token with permission to subscribe to KV event updates
with the [Vault event system](/vault/docs/concepts/events). For example, to
create a policy that grants access to static secret (KVv1 and KVv2) events:
```hcl
path "sys/events/subscribe/kv*" {
capabilities = ["read"]
}
```
Subscribing to KV events means that Proxy receives updates as soon as a secret
changes, which reduces staleness in the cache. Vault Proxy only checks for a
secret update if an event notification indicates that the related secret was
updated.
## Step 2: Ensure tokens have `capabilities-self` access
Tokens require `update` access to the
[`sys/capabilies-self`](/vault/api-docs/system/capabilities-self) endpoint to
request cached secrets. Vault tokens receive `update` permissions
[by default](/vault/docs/concepts/policies#default-policy). If you have modified
or removed the default policy, you must explicitly create a policy with the
appropriate permissions. For example:
```hcl
path "sys/capabilities-self" {
capabilities = ["update"]
}
```
## Step 3: Configure an appropriate refresh interval
By default, Vault Proxy refreshes tokens every five minutes. You can change the
default behavior and configure Proxy to verify and update cached token
capabilities with the `static_secret_token_capability_refresh_interval`
parameter in the `cache` configuration stanza. For example, to set a refresh
interval of one minute:
```hcl
cache {
cache_static_secrets = true
static_secret_token_capability_refresh_interval = "1m"
}
```
## Functionality
With static secret caching, Vault Proxy caches `GET` requests for KVv1 and KVv2
endpoints.
When a client sends a `GET` request for a new KV secret, Proxy forwards the
request to Vault but caches the response before forwarding it to the client. If
that client makes subsequent `GET` requests for the same secret, Vault Proxy
serves the cached response rather than forwarding the request to Vault.
Similarly, when a token requests access to a KV secret, it must complete a
success `GET` request. If the request is successful, Proxy caches the fact that
the token was successful in addition to the result. Subsequent requests by the
same token can then access this secret from the cache instead of Vault.
Vault Proxy uses the [event system](/vault/docs/concepts/events) to keep the
cache up to date. It monitors the KV event feed for events related to any secret
currently stored in the cache, including modification events like updates and
deletes. When Proxy detects a change in a cached secrete, it will update or
evict the cache entry as appropriate.
Vault Proxy also checks and refreshes the access permissions of known tokens
according to the window set with `static_secret_token_capability_refresh_interval`.
By default, the refresh interval is five minutes.
Every interval, Proxy calls [`sys/capabilies-self`](/vault/api-docs/system/capabilities-self) on
behalf of every token in the cache to confirm the token still has permission to
access the cached secret. If the result from Vault indicates that permission (or
the token itself) was revoked, Proxy updates the cache entry so that the affected
token can no longer access the relevant paths from the cache. The refresh interval
is essentially the maximum period after which permission to read a KV secret is
fully revoked for the relevant token.
For token refresh to work, any token that will access the cache also needs
`update` permission for [`sys/capabilies-self`](/vault/api-docs/system/capabilities-self).
Having `update` permission for the token lets Proxy test capabilities for the
token against multiple paths with a single request instead of testing for a `403`
response for each path explicitly.
<Tip title="Refresh is per token, not per secret">
If Proxy's API proxy is configured to use auto-authentication for tokens, and **all**
requests that pass through Vault Proxy use the same token, Proxy only
makes a single request to Vault every refresh interval, no matter how many
secrets are currently cached.
</Tip>
When static secret caching is enabled, Proxy returns `HIT` or `MISS` in the `X-Cache`
response header for requests so client can tell if the response was served from
the cache or forwarded from Vault. In the event of a hit, Proxy also sets the
`Age` header to indicate, in seconds, how old the cache entry is.
<Tip title="Old does not mean stale">
The fact that a cache entry is old, does not necessarily mean that the
information is out of date. Vault Proxy continually monitors KV events for
updates. A large value for `Age` may simply mean that the secret has not been
rotated recently.
</Tip>
## Configuration
The top level `cache` block has the following configuration entries relating to static secret caching:
- `cache_static_secrets` `(bool: false)` - Enables static secret caching when
set to `true`. When `cache_static_secrets` and `auth_auth` are both enabled,
Vault Proxy serves KV secrets directly from the cache to clients with
sufficient permission.
- `static_secret_token_capability_refresh_interval` `(duration: "5m", optional)` -
Sets the interval as a [duration format string](/vault/docs/concepts/duration-format)
at which Vault Proxy rechecks the permissions of tokens used to access cached
secrets. The refresh interval is the maximum period after which permission to
read a cached KV secret is fully revoked. Ignored when `cache_static_secrets`
is `false`.
### Example configuration
The following example Vault Proxy configuration:
- Defines a TCP listener (`listener`) with TLS disabled.
- Forces clients using API proxy (`api_proxy`) to identify with an auto-auth token.
- Configures auto-authentication (`auto-auth`) for `approle`.
- Enables static secret caching with `cache_static_secrets`.
- Sets an explicit token capability refresh window of 1 hour with `static_secret_token_capability_refresh_interval`.
```hcl
# Other Vault Proxy configuration blocks
# ...
cache {
cache_static_secrets = true
static_secret_token_capability_refresh_interval = "1h"
}
api_proxy {
use_auto_auth_token = "force"
}
listener "tcp" {
address = "127.0.0.1:8100"
tls_disable = true
}
auto_auth {
method {
type = "approle"
config = {
role_id_file_path = "roleid"
secret_id_file_path = "secretid"
remove_secret_id_file_after_reading = false
}
}
```
[event-system]: /vault/docs/concepts/events

38
website/content/docs/agent-and-proxy/proxy/versions.mdx
View File

@@ -2,21 +2,30 @@
layout: docs layout: docs
page_title: Vault Proxy Version Compatibility page_title: Vault Proxy Version Compatibility
description: |- description: |-
Guidelines for running different versions of Proxy and Server Guidelines for running different versions of Proxy and Vault server
--- ---
# Running different versions of proxy and server # Running different versions of Proxy and Vault server
There is no requirement to run identical versions of Vault Proxy and Vault Server. There is no requirement to run identical versions of Vault Proxy and Vault server.
It is safe to run different versions, however you may not be able to take advantage of all the newest features in Vault if you do not upgrade to the most recent versions of Proxy and Server. We recognize that this isn’t always possible, so we do support version mismatch as best as possible. It is safe to run different versions. However, you may not be able to take
advantage of all the newest features in Vault if you do not upgrade to
the most recent versions of Proxy and Vault server.
Proxy will write a note to its logs when it detects a mismatch between Proxy and Server. This is purely informative, intended to assist with debugging in case the mismatch is given rise to problems, e.g. because a newer Proxy version is trying to make use of functionality that doesn't exist in the Server version it's talking to. If Proxy is behaving acceptably, the message may be ignored. Proxy writes a note to the logs when it detects a mismatch between
Proxy and Vault server versions. The note is purely informative to assist
with debugging when the problem may be related to a version mismatch.
For example, when a newer Proxy version expects functionality that is
not available in an older version of Vault.
This document describes the common cases. There may be occasional exceptions, which if intentional will be called out in the CHANGELOG in a `CHANGES` section. If unintentional/undocumented these should be treated as bugs and reported. This document describes the common cases. There may be occasional exceptions, which if intentional will be called out in the CHANGELOG in a `CHANGES` section. If unintentional/undocumented these should be treated as bugs and reported.
## Older version of proxy than server ## Older version of Proxy than Vault server
We do not anticipate any problems stemming from continuing to run an older Proxy version after the server nodes are upgraded to a later version. Existing deployments using Proxy should not be impacted, as we don't generally make backwards-incompatible changes to Vault Server. In most cases, Vault server upgrades are backwards compatible with
older versions of Vault Proxy. In the rare case where a Vault upgrade is
**not** backwards compatible, we document the relevant information in
the Vault upgrade guide.
Auto-auth: Auto-auth:
- new auth methods that have been introduced since Proxy was built will be unavailable - new auth methods that have been introduced since Proxy was built will be unavailable
@@ -25,14 +34,19 @@ Auto-auth:
Proxy: Proxy:
- since Proxy simply mirrors the incoming requests, even if an incoming request uses an endpoint that didn't exist when that version of Proxy was compiled, that won't impede Proxy's ability to proxy the request - since Proxy simply mirrors the incoming requests, even if an incoming request uses an endpoint that didn't exist when that version of Proxy was compiled, that won't impede Proxy's ability to proxy the request
## Newer version of proxy than server ## Newer version of Proxy than Vault server
It is possible that an Proxy could depend on features that don’t exist in older Server versions. Newer Vault Agent versions will not work with older versions of Vault if
the Proxy depends on features that do not exist in older Vault server
versions. Whenever possible, we release newer functionality as opt-in
and provide graceful degradation when connecting to an older Vault
server instance. But the new functionality may be required in cases
where the change relates unless there's a very good reason (such as a
serious security flaw being patched)
Auto-auth: Auto-auth:
- Proxy may claim to support newer auth methods that have been introduced since Server was built, but they won't work due to Server not supporting them - Proxy may support authentication methods that are unavailable in older versions of Vault.
- Proxy may make use of new functionality for existing auth methods that isn't available in an older Server you're using - Proxy may make use of newer functionality for existing authentication methods.
- Generally we will try to make such a change be opt-in, or to gracefully degrade when connecting to an older Server instance, unless there's a very good reason (such as a serious security flaw being patched)
Proxy: Proxy:
- since Proxy simply mirrors the incoming requests, it is unlikely that incompatibilities would surface in proxying, but new functionality may not be available - since Proxy simply mirrors the incoming requests, it is unlikely that incompatibilities would surface in proxying, but new functionality may not be available

4
website/data/docs-nav-data.json
View File

@@ -1100,6 +1100,10 @@
"title": "Overview", "title": "Overview",
"path": "agent-and-proxy/proxy/caching" "path": "agent-and-proxy/proxy/caching"
}, },
{
"title": "Static Secret Caching",
"path": "agent-and-proxy/proxy/caching/static-secret-caching"
},
{ {
"title": "Persistent Caching", "title": "Persistent Caching",
"routes": [ "routes": [