diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx index ba407df70302..3ca84458af5f 100644 --- a/website/content/docs/agent/index.mdx +++ b/website/content/docs/agent/index.mdx @@ -8,21 +8,96 @@ description: |- # Vault Agent -Vault Agent is a client daemon that provides the following features: +A valid client token must accompany most requests to Vault. This +includes all API requests, as well as via the Vault CLI and other libraries. +Therefore, Vault clients must first authenticate with Vault to acquire a token. +Vault provides several different authentication methods to assist in +delivering this initial token. + +![Client authentication](/img/diagram-vault-agent.png) + +If the client can securely acquire the token, all subsequent requests (e.g., request +database credentials, read key/value secrets) are processed based on the +trust established by a successful authentication. + +This means that client application must invoke the Vault API to authenticate +with Vault and manage the acquired token, in addition to invoking the API to +request secrets from Vault. This implies code changes to client applications +along with additional testing and maintenance of the application. + +The following code example implements Vault API to authenticate with Vault +through [AppRole auth method](/docs/auth/approle#code-example), and then uses +the returned client token to read secrets at `kv-v2/data/creds`. + +```go +package main + +import ( + ...snip... + vault "github.com/hashicorp/vault/api" +) + +// Fetches a key-value secret (kv-v2) after authenticating via AppRole +func getSecretWithAppRole() (string, error) { + config := vault.DefaultConfig() + + client := vault.NewClient(config) + wrappingToken := ioutil.ReadFile("path/to/wrapping-token") + unwrappedToken := client.Logical().Unwrap(strings.TrimSuffix(string(wrappingToken), "\n")) + + secretID := unwrappedToken.Data["secret_id"] + roleID := os.Getenv("APPROLE_ROLE_ID") + + params := map[string]interface{}{ + "role_id": roleID, + "secret_id": secretID, + } + resp := client.Logical().Write("auth/approle/login", params) + client.SetToken(resp.Auth.ClientToken) -- [Auto-Auth][autoauth] - Automatically authenticate to Vault and manage the token renewal process for locally-retrieved dynamic secrets. -- [Caching][caching] - Allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens. -- [Windows Service][winsvc] - Allows running the Vault Agent as a Windows service. -- [Templating][template] - Allows rendering of user supplied templates by Vault Agent, using the token generated by the Auto-Auth step. - To get help, run: + secret, err := client.Logical().Read("kv-v2/data/creds") + if err != nil { + return "", fmt.Errorf("unable to read secret: %w", err) + } -```shell-session -$ vault agent -h + data := secret.Data["data"].(map[string]interface{}) + + ...snip... +} ``` +For some Vault deployments, making (and maintaining) these changes to +applications may not be a problem, and may actually be preferred. This may be +applied to scenarios where you have a small number of applications or you want +to keep strict, customized control over how each application interacts with +Vault. However, in other situations where you have a large number of +applications, as in large enterprises, you may not have the resources or expertise +to update and maintain the Vault integration code for every application. When +third party applications are being deployed by the application, it is prohibited +to add the Vault integration code. + +Vault Agent aims to remove this initial hurdle to adopt Vault by providing a +more scalable and simpler way for applications to integrate with Vault. + + +## What is Vault Agent? + +Vault Agent is a client daemon that provides the following features: + +- [Auto-Auth][autoauth] - Automatically authenticate to Vault and manage the +token renewal process for locally-retrieved dynamic secrets. +- [Caching][caching] - Allows client-side caching of responses containing newly +created tokens and responses containing leased secrets generated off of these +newly created tokens. The agent also manages the renewals of the cached tokens and leases. +- [Windows Service][winsvc] - Allows running the Vault Agent as a Windows +service. +- [Templating][template] - Allows rendering of user-supplied templates by Vault +Agent, using the token generated by the Auto-Auth step. + + ## Auto-Auth -Vault Agent allows for easy authentication to Vault in a wide variety of +Vault Agent allows easy authentication to Vault in a wide variety of environments. Please see the [Auto-Auth docs][autoauth] for information. @@ -143,6 +218,31 @@ supports an additional optional entry: Request Forgery attacks. Requests on the listener that do not have the proper `X-Vault-Request` header will fail, with a HTTP response status code of `412: Precondition Failed`. + +## Start Vault Agent + +To run Vault Agent: + +1. [Download](/downloads) the Vault binary where the client application runs +(virtual machine, Kubernetes pod, etc.) + +1. Create a Vault Agent configuration file. (See the [Example +Configuration](#example-configuration) section for an example configuration.) + +1. Start a Vault Agent with the configuration file. + + **Example:** + + ```shell-session + $ vault server -config=/etc/vault/agent-config.hcl + ``` + + To get help, run: + + ```shell-session + $ vault agent -h + ``` + ## Example Configuration An example configuration, with very contrived values, follows: diff --git a/website/public/img/diagram-vault-agent.png b/website/public/img/diagram-vault-agent.png new file mode 100644 index 000000000000..4c95ee4fa4d0 Binary files /dev/null and b/website/public/img/diagram-vault-agent.png differ