Update Vault Agent intro (#13267)
* Update Vault Agent intro * Update website/content/docs/agent/index.mdx Co-authored-by: Brian Shumate <brianshumate@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Brian Shumate <brianshumate@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Brian Shumate <brianshumate@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Update website/content/docs/agent/index.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> Co-authored-by: Brian Shumate <brianshumate@users.noreply.github.com> Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
This commit is contained in:
Yoko Hyakuna
GitHub
parent
4e05632881
commit
6ea0df030e
|
|
@ -8,21 +8,96 @@ description: |-
|
||||||
|
|
||||||
# Vault Agent
|
# Vault Agent
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
secret, err := client.Logical().Read("kv-v2/data/creds")
|
||||||
|
if err != nil {
|
||||||
|
return "", fmt.Errorf("unable to read secret: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
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:
|
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.
|
- [Auto-Auth][autoauth] - Automatically authenticate to Vault and manage the
|
||||||
- [Caching][caching] - Allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens.
|
token renewal process for locally-retrieved dynamic secrets.
|
||||||
- [Windows Service][winsvc] - Allows running the Vault Agent as a Windows service.
|
- [Caching][caching] - Allows client-side caching of responses containing newly
|
||||||
- [Templating][template] - Allows rendering of user supplied templates by Vault Agent, using the token generated by the Auto-Auth step.
|
created tokens and responses containing leased secrets generated off of these
|
||||||
To get help, run:
|
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.
|
||||||
|
|
||||||
```shell-session
|
|
||||||
$ vault agent -h
|
|
||||||
```
|
|
||||||
|
|
||||||
## Auto-Auth
|
## 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]
|
environments. Please see the [Auto-Auth docs][autoauth]
|
||||||
for information.
|
for information.
|
||||||
|
|
||||||
|
|
@ -143,6 +218,31 @@ supports an additional optional entry:
|
||||||
Request Forgery attacks. Requests on the listener that do not have the proper
|
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`.
|
`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
|
## Example Configuration
|
||||||
|
|
||||||
An example configuration, with very contrived values, follows:
|
An example configuration, with very contrived values, follows:
|
||||||
|
|
|
||||||
BIN
website/public/img/diagram-vault-agent.png
(Stored with Git LFS)
Normal file
BIN
website/public/img/diagram-vault-agent.png
(Stored with Git LFS)
Normal file
Binary file not shown.
Loading…
Reference in a new issue