scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-10-30 02:02:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOCS] SEO updates for Vault Agent docs (#28972)

Browse Source 
* Update Vault Agent docs

* Update left-hand nav

* tweak caching titles

* tweak deprecation/warning

* tweaks to match proxy updates
This commit is contained in:
Sarah Chavis
2024-11-20 14:31:20 -08:00
committed by GitHub
parent a0ceaf6772
commit fd00bbfd1b
12 changed files with 176 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,20 +1,18 @@
---
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
@@ -22,7 +20,7 @@ switch to using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API proxyin
recommend using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API Proxy
related workflows.
</Note>
</Warning>
## Functionality

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

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

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

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

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

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

124
website/content/docs/agent-and-proxy/agent/generate-config.mdx Normal file
View File

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

129
website/content/docs/agent-and-proxy/agent/generate-config/index.mdx
View File

@@ -1,129 +0,0 @@
---
layout: docs
page_title: agent generate-config - Command
description: |-
Generates a simple Vault Agent configuration file from the given parameters.
---
# agent generate-config
Generates a simple Vault Agent configuration file from the given parameters.
Currently, the only supported configuration type is `env-template`, which
helps you generate a configuration file with environment variable templates
for running Vault Agent in
[process supervisor](/vault/docs/agent-and-proxy/agent/process-supervisor)
mode.
For every specified secret `-path`, the command will attempt to generate one or
multiple `env_template` entries based on the `JSON` key(s) stored in the
specified secret. If the secret `-path` ends with `/*`, the command will
attempt to recurse through the secrets tree rooted at the given path,
generating `env_template` entries for each encountered secret. Currently,
only [kv-v1](/vault/docs/secrets/kv/kv-v1) and
[kv-v2](/vault/docs/secrets/kv/kv-v2) paths are supported.
The command specified in the `-exec` option will be used to generate an
`exec` entry, which will tell Vault Agent which child process to run.
In addition to the `env_template` entries, the command generates an `auto_auth`
section with `token_file` authentication method. While this method is very
convenient for local testing, it should **NOT** be used in production. In a
production environment, please use any other
[Auto-Auth method](/vault/docs/agent-and-proxy/autoauth/methods) instead.
By default, the file will be generated in the local directory as `agent.hcl`
unless a path is specified as an argument.
## Example
Before generating a configuration file, let's insert a secret `foo`:
```shell-session
$ vault kv put -mount=secret foo user="admin" password="s3cr3t"
```
Generate an agent configuration file which will reference `secret/foo`:
```shell-session
$ vault agent generate-config \
-type="env-template" \
-exec="./my-app arg1 arg2" \
-namespace="my/ns/" \
-path="secret/foo" \
my-config.hcl
```
**Expected output:**
<CodeBlockConfig hideClipboard>
```plaintext
Successfully generated "my-config.hcl" configuration file!
Warning: the generated file uses 'token_file' authentication method, which is not suitable for production environments.
```
</CodeBlockConfig>
This will produce `my-config.hcl` file in the current directory with contents
similar to the following:
```hcl
auto_auth {
method {
type = "token_file"
config {
token_file_path = "/Users/avean/.vault-token"
}
}
}
template_config {
static_secret_render_interval = "5m"
exit_on_retry_failure = true
max_connections_per_host = 10
}
vault {
address = "http://localhost:8200"
}
env_template "FOO_PASSWORD" {
contents = "{{ with secret \"secret/data/foo\" }}{{ .Data.data.password }}{{ end }}"
error_on_missing_key = true
}
env_template "FOO_USER" {
contents = "{{ with secret \"secret/data/foo\" }}{{ .Data.data.user }}{{ end }}"
error_on_missing_key = true
}
exec {
command = ["./my-app", "arg1", "arg2"]
restart_on_secret_changes = "always"
restart_stop_signal = "SIGTERM"
}
```
## Usage
The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included in all commands.
- `type` `(string: <required>)` - The type of configuration file to generate;
currently, only `env-template` is supported.
- `path` `(string: "")` - Path to a kv-v1 or kv-v2 secret
(e.g. `secret/data/foo`, `kv-v2/my-app/*`); multiple secrets and tail `*`
wildcards are allowed.
- `-exec` `(string: "env")` - The command to execute in agent process
supervisor mode.
## Tutorial
Refer to the [Vault Agent - secrets as environment
variables](/vault/tutorials/vault-agent/agent-env-vars) tutorial for an
end-to-end example.

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

@@ -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?

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

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

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

@@ -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))

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

@@ -1,11 +1,12 @@
---
layout: docs
page_title: Vault Agent Version Compatibility
description: |-
Guidelines for running different versions of Agent and Vault server
page_title: Risks of using inconsistent versions of Agent and Vault
description: >-
Using different versions of Vault Agent and Vault is possible but limits the
available functionality.
---
# Running different versions of Agent and Vault server
# Understand the risks of using inconsistent versions of Agent and Vault
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

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

@@ -1,11 +1,11 @@
---
layout: docs
page_title: Vault Agent Windows Service
page_title: Run Vault Agent as a Windows service
description: >-
Vault Agent can be run as a Windows service.
Run Vault Agent as a Windows service
---
# Vault Agent Windows service
# Run Vault Agent as a 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
Service Control Manager. After Vault Agent is registered, it can be started like any other Windows

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

@@ -1330,29 +1330,29 @@
"title": "Vault Agent",
"routes": [
{
"title": "Overview",
"title": "What is Vault Agent?",
"path": "agent-and-proxy/agent"
},
{
"title": "API Proxy",
"title": "Vault Agent as Vault API proxy",
"path": "agent-and-proxy/agent/apiproxy"
},
{
"title": "Caching",
"title": "Vault Agent caching",
"routes": [
{
"title": "Overview",
"path": "agent-and-proxy/agent/caching"
},
{
"title": "Persistent Caching",
"title": "Persistent caching",
"routes": [
{
"title": "Overview",
"title": "Use built-in persistent caching",
"path": "agent-and-proxy/agent/caching/persistent-caches"
},
{
"title": "Kubernetes",
"title": "Use Kubernetes persistent cache",
"path": "agent-and-proxy/agent/caching/persistent-caches/kubernetes"
}
]
@@ -1360,23 +1360,23 @@
]
},
{
"title": "generate-config",
"title": "Generate a development config file",
"path": "agent-and-proxy/agent/generate-config"
},
{
"title": "Process Supervisor Mode",
"title": "Run in process supervisor mode",
"path": "agent-and-proxy/agent/process-supervisor"
},
{
"title": "Templates",
"title": "Use Vault Agent templates",
"path": "agent-and-proxy/agent/template"
},
{
"title": "Windows service",
"title": "Run Vault Agent as a Windows service",
"path": "agent-and-proxy/agent/winsvc"
},
{
"title": "Version compatibility",
"title": "Risks of inconsistent Agent and Vault versions",
"path": "agent-and-proxy/agent/versions"
}
]