docs: add persistent cache (#11272)

* 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>

website/content/docs/agent/caching.mdx → 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

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.

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`.

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",