Skip to content

Commit

Permalink
docs: add persistent cache (#11272)
Browse files Browse the repository at this point in the history
* docs: add persistent cache

* Clarify documentation

* Update website/content/docs/agent/caching/index.mdx

Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>

* Update website/content/docs/agent/caching/persistent-caches/kubernetes.mdx

Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>

* Update index.mdx

* Update website/content/docs/agent/caching/index.mdx

Co-authored-by: Calvin Leung Huang <cleung2010@gmail.com>

* Update website/content/docs/agent/caching/index.mdx

Co-authored-by: Calvin Leung Huang <cleung2010@gmail.com>

* Update index.mdx

* Update kubernetes.mdx

* Resolve conflicts

Co-authored-by: Theron Voran <tvoran@users.noreply.github.com>
Co-authored-by: Calvin Leung Huang <cleung2010@gmail.com>
  • Loading branch information
3 people authored Apr 8, 2021
1 parent 2df57a0 commit 60f3ba9
Show file tree
Hide file tree
Showing 4 changed files with 132 additions and 1 deletion.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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`.
20 changes: 19 additions & 1 deletion website/data/docs-nav-data.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down

0 comments on commit 60f3ba9

Please sign in to comment.