From 73452bab5f995cc1f584e2e739876dcaffe70307 Mon Sep 17 00:00:00 2001 From: Sarah Chavis <62406755+schavis@users.noreply.github.com> Date: Wed, 20 Nov 2024 22:31:20 +0000 Subject: [PATCH] backport of commit fd00bbfd1b6c9f6e873d66071773ad066258c388 --- .../docs/agent-and-proxy/agent/apiproxy.mdx | 16 +-- .../agent-and-proxy/agent/caching/index.mdx | 11 +- .../agent/caching/persistent-caches/index.mdx | 7 +- .../caching/persistent-caches/kubernetes.mdx | 7 +- .../agent-and-proxy/agent/generate-config.mdx | 124 +++++++++++++++++ .../agent/generate-config/index.mdx | 129 ------------------ .../docs/agent-and-proxy/agent/index.mdx | 8 +- .../agent/process-supervisor.mdx | 9 +- .../docs/agent-and-proxy/agent/template.mdx | 8 +- .../docs/agent-and-proxy/agent/versions.mdx | 9 +- .../docs/agent-and-proxy/agent/winsvc.mdx | 6 +- website/data/docs-nav-data.json | 22 +-- 12 files changed, 176 insertions(+), 180 deletions(-) create mode 100644 website/content/docs/agent-and-proxy/agent/generate-config.mdx delete mode 100644 website/content/docs/agent-and-proxy/agent/generate-config/index.mdx diff --git a/website/content/docs/agent-and-proxy/agent/apiproxy.mdx b/website/content/docs/agent-and-proxy/agent/apiproxy.mdx index 636b99167477..9ed6eea006a4 100644 --- a/website/content/docs/agent-and-proxy/agent/apiproxy.mdx +++ b/website/content/docs/agent-and-proxy/agent/apiproxy.mdx @@ -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. - - + [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. - + ## Functionality diff --git a/website/content/docs/agent-and-proxy/agent/caching/index.mdx b/website/content/docs/agent-and-proxy/agent/caching/index.mdx index 6d8e49fe862f..db58a1898c48 100644 --- a/website/content/docs/agent-and-proxy/agent/caching/index.mdx +++ b/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 diff --git a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx b/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx index 9ae86cadb266..c889765df0bb 100644 --- a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx +++ b/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 diff --git a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx b/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx index 46fdad01f82a..f773dc665ef3 100644 --- a/website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx +++ b/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 diff --git a/website/content/docs/agent-and-proxy/agent/generate-config.mdx b/website/content/docs/agent-and-proxy/agent/generate-config.mdx new file mode 100644 index 000000000000..96a226e07297 --- /dev/null +++ b/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**. + + + +- 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. + + + +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 " " \ + -namespace "" \ + -path "" \ + -path "" \ + ... + -path "" \ + +``` + +For example: + + + +```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. +``` + + + +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 `_`. + +For example: + + + +```hcl +auto_auth { + + method { + type = "token_file" + + config { + token_file_path = "/home//.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" +} +``` + + diff --git a/website/content/docs/agent-and-proxy/agent/generate-config/index.mdx b/website/content/docs/agent-and-proxy/agent/generate-config/index.mdx deleted file mode 100644 index 4f66f5f6aa2f..000000000000 --- a/website/content/docs/agent-and-proxy/agent/generate-config/index.mdx +++ /dev/null @@ -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:** - - - -```plaintext -Successfully generated "my-config.hcl" configuration file! -Warning: the generated file uses 'token_file' authentication method, which is not suitable for production environments. -``` - - - -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: )` - 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. diff --git a/website/content/docs/agent-and-proxy/agent/index.mdx b/website/content/docs/agent-and-proxy/agent/index.mdx index 48855f7ebe83..d0ad6f2f30eb 100644 --- a/website/content/docs/agent-and-proxy/agent/index.mdx +++ b/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? diff --git a/website/content/docs/agent-and-proxy/agent/process-supervisor.mdx b/website/content/docs/agent-and-proxy/agent/process-supervisor.mdx index 210967aeb0e7..359628e4c965 100644 --- a/website/content/docs/agent-and-proxy/agent/process-supervisor.mdx +++ b/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 diff --git a/website/content/docs/agent-and-proxy/agent/template.mdx b/website/content/docs/agent-and-proxy/agent/template.mdx index 4a003e057a0b..eb91b8782fce 100644 --- a/website/content/docs/agent-and-proxy/agent/template.mdx +++ b/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)) diff --git a/website/content/docs/agent-and-proxy/agent/versions.mdx b/website/content/docs/agent-and-proxy/agent/versions.mdx index 9d8e6a64cffc..6c727e0d9ee5 100644 --- a/website/content/docs/agent-and-proxy/agent/versions.mdx +++ b/website/content/docs/agent-and-proxy/agent/versions.mdx @@ -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 diff --git a/website/content/docs/agent-and-proxy/agent/winsvc.mdx b/website/content/docs/agent-and-proxy/agent/winsvc.mdx index 3abce12a48a2..863ade7c14ae 100644 --- a/website/content/docs/agent-and-proxy/agent/winsvc.mdx +++ b/website/content/docs/agent-and-proxy/agent/winsvc.mdx @@ -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 diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 876108b7fd23..17fc8d47597a 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -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" } ]