backport of commit fd00bbf (#28976)

Co-authored-by: Sarah Chavis <[email protected]>

website/content/docs/agent-and-proxy/agent/apiproxy.mdx

@@ -1,28 +1,26 @@
 ---
 layout: docs
-page_title: Vault Agent API Proxy
+page_title: Use Vault Agent as an API proxy
 description: >-
-  Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
-  for Vault's API.
+  Use auto-authentication and configure Vault Agent as a proxy for the Vault API.
 ---
 
-# Vault Agent API proxy
+# Use Vault Agent as an API proxy
+
+@include 'alerts/deprecated.mdx'
 
 Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
 for Vault's API.
 
-~> 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.
-
-<Note title="Use Vault Proxy for static secret caching">
+<Warning 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>
+</Warning>
 
 ## Functionality
 

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

@@ -1,13 +1,12 @@
 ---
 layout: docs
-page_title: Vault Agent Caching
-description: |-
-  Vault Agent Caching allows client-side caching of responses containing newly
-  created tokens and responses containing leased secrets generated off of these
-  newly created tokens.
+page_title: Vault Agent caching overview
+description: >-
+  Use client-side caching with Vault Agent for responses with newly
+  created tokens or leased secrets generated from a newly created token.
 ---
 
-# Vault Agent caching
+# Vault Agent caching overview
 
 <Note title="Use Vault Proxy for static secret caching">
 

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

@@ -1,10 +1,11 @@
 ---
 layout: docs
-page_title: Vault Agent Persistent Caching
-description: Vault Agent Caching
+page_title: Use built-in persistent caching - Vault Agent
+description: >-
+  Use persistent caching with Vault Agent
 ---
 
-# Vault Agent persistent caching
+# Use built-in persistent caching
 
 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

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

@@ -1,10 +1,11 @@
 ---
 layout: docs
-page_title: Kubernetes - Vault Agent Persistent Cache
-description: Kubernetes Persistent Cache for Vault Agent Caching
+page_title: Use Kubernetes persistent cache - Vault Agent
+description: >-
+  Configure Vault Agent to use Kubernetes for persistent cache
 ---
 
-# Vault Agent Kubernetes persistent cache
+# Use 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

website/content/docs/agent-and-proxy/agent/generate-config.mdx

@@ -0,0 +1,124 @@
+---
+layout: docs
+page_title: Generate a development configuration file
+description: >-
+  Use the Vault CLI to create a basic development configuration file to run
+  Vault Agent in process supervisor mode.
+---
+
+# Generate a Vault Agent development configuration file
+
+Use the Vault CLI to create a basic development configuration file to run Vault
+Agent in process supervisor mode.
+
+Development configuration files include an `auto_auth` section that reference a
+token file based on the Vault token used to authenticate the CLI command. Token
+files are convenient for local testing but **are not** appropriate for in
+production. **Always use a robust
+[auto-authentication method](/vault/docs/agent-and-proxy/autoauth/methods) in
+production**.
+
+<Tip title="Assumptions">
+
+- You have [set up a `kv` v2 plugin](/vault/docs/secrets/kv/kv-v2/setup).
+- Your authentication token has `read` permissions for the `kv` v2 plugin.
+
+</Tip>
+
+Use [`vault agent generate-config`](/vault/docs/commands/agent/generate-config)
+to create a development configuration file with environment variable templates:
+
+```shell-session
+$ vault agent generate-config
+    -type "env-template"                                \
+    -exec "<path_to_child_process> <list_of_arguments>" \
+    -namespace "<plugin_namespace>"                     \
+    -path "<mount_path_to_kv_plugin_1>"                 \
+    -path "<mount_path_to_kv_plugin_2>"                 \
+    ...
+    -path "<mount_path_to_kv_plugin_N>"                 \
+    <config_file_name>
+```
+
+For example:
+
+<CodeBlockConfig hideClipboard>
+
+```shell-session
+$ vault agent generate-config             \
+         -type="env-template"             \
+         -exec="./payment-app 'wf-test'"  \
+         -namespace="testing"             \
+         -path="shared/dev/*"             \
+         -path="private/ci/integration"   \
+         agent-config.hcl
+
+Successfully generated "agent-config.hcl" configuration file!
+Warning: the generated file uses 'token_file' authentication method, which is not suitable for production environments.
+```
+
+</CodeBlockConfig>
+
+The configuration file includes `env_template` entries for each key stored at
+the explicit paths and any key encountered while recursing through paths ending
+with `/*`. Template keys have the form `<final_path_segment>_<key_name>`.
+
+For example:
+
+<CodeBlockConfig highlight="7,22,26,30,34,38,42">
+
+```hcl
+auto_auth {
+
+  method {
+    type = "token_file"
+
+    config {
+      token_file_path = "/home/<username>/.vault-token"
+    }
+  }
+}
+
+template_config {
+  static_secret_render_interval = "5m"
+  exit_on_retry_failure         = true
+  max_connections_per_host      = 10
+}
+
+vault {
+  address = "http://192.168.0.1:8200"
+}
+
+env_template "SQUARE_API_PROD" {
+  contents             = "{{ with secret \"shared/data/dev/square-api\" }}{{ .Data.data.prod }}{{ end }}"
+  error_on_missing_key = true
+}
+env_template "SQUARE_API_SANDBOX" {
+  contents             = "{{ with secret \"shared/data/dev/square-api\" }}{{ .Data.data.sandbox }}{{ end }}"
+  error_on_missing_key = true
+}
+env_template "SQUARE_API_SMOKE" {
+  contents             = "{{ with secret \"shared/data/dev/square-api\" }}{{ .Data.data.smoke }}{{ end }}"
+  error_on_missing_key = true
+}
+env_template "SEEDS_SEED1" {
+  contents             = "{{ with secret \"shared/data/dev/seeds\" }}{{ .Data.data.seed1 }}{{ end }}"
+  error_on_missing_key = true
+}
+env_template "SEEDS_SEED2" {
+  contents             = "{{ with secret \"shared/data/dev/seeds\" }}{{ .Data.data.seed2 }}{{ end }}"
+  error_on_missing_key = true
+}
+env_template "DEV_POSTMAN" {
+  contents             = "{{ with secret \"private/data/ci/integration\" }}{{ .Data.data.postman }}{{ end }}"
+  error_on_missing_key = true
+}
+
+exec {
+  command                   = ["./payment-app", "'wf-test'"]
+  restart_on_secret_changes = "always"
+  restart_stop_signal       = "SIGTERM"
+}
+```
+
+</CodeBlockConfig>

website/content/docs/agent-and-proxy/agent/index.mdx

@@ -1,9 +1,9 @@
 ---
 layout: docs
-page_title: Vault Agent
-description: |-
-  Vault Agent is a client-side daemon that can be used to perform some Vault
-  functionality automatically.
+page_title: What is Vault Agent?
+description: >-
+  Vault Agent is a client-side daemon that securely extracts secrets from Vault
+  for clients without the complexity of API calls.
 ---
 
 # What is Vault Agent?

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

@@ -1,12 +1,13 @@
 ---
 layout: docs
-page_title: Vault Agent's Process Supervisor Mode
+page_title: Run Vault Agent in process supervisor mode
 description: >-
-  Vault Agent's Process Supervisor Mode allows Vault secrets to be injected
-  into a process via environment variables using Consul Template markup.
+  Run Vault Agent in process supervisor mode to write Vault secrets to
+  environment variables for use in external processes.
+
 ---
 
-# Vault Agent's Process Supervisor mode
+# Run Vault Agent in process supervisor mode
 
 Vault Agent's Process Supervisor Mode allows Vault secrets to be injected into
 a process via environment variables using

website/content/docs/agent-and-proxy/agent/template.mdx

@@ -1,12 +1,12 @@
 ---
 layout: docs
-page_title: Vault Agent Template
+page_title: Use Vault Agent templates
 description: >-
-  Vault Agent's Template functionality allows Vault secrets to be rendered to
-  files using Consul Template markup.
+  Use templates with Vault Agent to write Vault secrets files with Consul
+  Template markup.
 ---
 
-# Vault Agent templates
+# Use Vault Agent templates
 
 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))