Update Vault Agent intro

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: