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
|
||||
|
||||
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:
|
||||
|
||||
- [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:
|
||||
- [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.
|
||||
|
||||
```shell-session
|
||||
$ vault agent -h
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
|
|
|||
Binary file not shown.
Loading…
Reference in New Issue