Docs: Enterprise Vault feature (#25895)

* Docs: Vault integration

* Add links to vault feature doc

* Update Enterprise configuration file with vault fields

* Small fixes on vault doc

* Update docs according to PR review

* Update docs/sources/administration/configuration.md

Co-authored-by: Leonard Gram <leo@xlson.com>

* Update docs/sources/enterprise/vault.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/enterprise/vault.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

Co-authored-by: Emil Tullstedt <emil.tullstedt@grafana.com>
Co-authored-by: Leonard Gram <leo@xlson.com>
Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

docs/sources/administration/configuration.md

@@ -91,12 +91,14 @@ export GF_PLUGIN_GRAFANA_IMAGE_RENDERER_RENDERING_IGNORE_HTTPS_ERRORS=true
 
 > Only available in Grafana 7.1+.
 
+> For any changes to `conf/grafana.ini` (or corresponding environment variables) to take effect, you must restart Grafana.
+
 If any of your options contains the expression `$__<provider>{<argument>}`
 or `${<environment variable>}`, then they will be processed by Grafana's
 variable expander. The expander runs the provider with the provided argument
 to get the final value of the option.
 
-There are two providers: `env` and `file`.
+There are three providers: `env`, `file`, and `vault`.
 
 ### Env provider
 
@@ -108,7 +110,7 @@ Grafana's log directory would be set to the `grafana` directory in the
 directory behind the `LOGDIR` environment variable in the following
 example.
 
-```
+```ini
 [paths]
 logs = $__env{LOGDIR}/grafana
 ```
@@ -120,12 +122,16 @@ beginning and the end of files.
 The database password in the following example would be replaced by
 the content of the `/etc/secrets/gf_sql_password` file:
 
-```
+```ini
 [database]
 password = $__file{/etc/secrets/gf_sql_password}
 ```
 
-> For any changes to `conf/grafana.ini` (or corresponding environment variables) to take effect, you must restart Grafana for the changes to take effect.
+### Vault provider
+
+The `vault` provider allows you to manage your secrets with [Hashicorp Vault](https://www.hashicorp.com/products/vault).
+
+> Vault provider is only available in Grafana Enterprise v7.1+. For more information, refer to [Vault integration]({{< relref "../enterprise/vault.md" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).
 
 <hr />
 

docs/sources/enterprise/_index.md

@@ -54,6 +54,7 @@ With Grafana Enterprise, you get access to new features, including:
 * [Export dashboard as PDF]({{< relref "export-pdf.md" >}})
 * [White labeling]({{< relref "white-labeling.md" >}}) to customize Grafana from the brand and logo to the footer links.
 * [Usage insights]({{< relref "usage-insights.md" >}}) to understand how your Grafana instance is used.
+* [Vault integration]({{< relref "vault.md" >}}) to manage your configuration or provisioning secrets with Vault.
 
 ## Enterprise plugins
 

docs/sources/enterprise/enterprise-configuration.md

@@ -186,3 +186,33 @@ List of comma- or space-separated roles that will be mapped to the Admin role.
 ### role_values_grafana_admin
 
 List of comma- or space-separated roles that will be mapped to the Grafana Admin (Super Admin) role.
+
+## [keystore.vault]
+
+### url
+
+Location of the Vault server.
+
+### namespace
+
+Vault namespace if using Vault with multi-tenancy.
+
+### auth_method
+
+Method for authenticating towards Vault. Vault is inactive if this option is not set. Current possible values: `token`.
+
+### token
+
+Secret token to connect to Vault when auth_method is `token`.
+
+### lease_renewal_interval
+
+Time between checking if there are any secrets which needs to be renewed.
+
+### lease_renewal_expires_within
+
+Time until expiration for tokens which are renewed. Should have a value higher than lease_renewal_interval.
+
+### lease_renewal_increment
+
+New duration for renewed tokens. Vault may be configured to ignore this value and impose a stricter limit.

docs/sources/enterprise/vault.md

@@ -0,0 +1,139 @@
++++
+title = "Vault"
+description = ""
+keywords = ["grafana", "vault", "configuration"]
+type = "docs"
+[menu.docs]
+parent = "enterprise"
+weight = 700
++++
+
+# Vault integration
+
+> Only available in Grafana Enterprise v7.1+.
+
+If you manage your secrets with [Hashicorp Vault](https://www.hashicorp.com/products/vault), you can use them for [Configuration]({{< relref "../administration/configuration.md" >}})
+and [Provisioning]({{< relref "../administration/provisioning.md" >}}).
+
+> **Note:** If you have Grafana set up for [high availability]({{< relref "../tutorials/ha_setup.md" >}}), then we advise not to use dynamic secrets for provisioning files.
+> Each Grafana instance is responsible for renewing its own leases. Your data source leases might expire when one of your Grafana servers shuts down.
+
+## Configuration
+
+Before using Vault, you need to activate it by providing a URL, authentication method (currently only token),
+and a token for your Vault service. Grafana automatically renews the service token if it is renewable and
+set up with a limited lifetime.
+
+If you're using short-lived leases, then you can also configure how often Grafana should renew the lease and for
+how long. We recommend keeping the defaults unless you run into problems.
+
+```ini
+[keystore.vault]
+# Location of the Vault server
+;url =
+# Vault namespace if using Vault with multi-tenancy
+;namespace =
+# Method for authenticating towards Vault. Vault is inactive if this option is not set
+# Possible values: token
+;auth_method =
+# Secret token to connect to Vault when auth_method is token
+;token =
+# Time between checking if there are any secrets which needs to be renewed.
+;lease_renewal_interval = 5m
+# Time until expiration for tokens which are renewed. Should have a value higher than lease_renewal_interval
+;lease_renewal_expires_within = 15m
+# New duration for renewed tokens. Vault may be configured to ignore this value and impose a stricter limit.
+;lease_renewal_increment = 1h
+```
+
+Example for `vault server -dev`:
+
+```ini
+[keystore.vault]
+url = http://127.0.0.1:8200 # HTTP should only be used for local testing
+auth_method = token
+token = s.sAZLyI0r7sFLMPq6MWtoOhAN # replace with your key
+```
+
+## Using the Vault expander
+
+After you configure Vault, you must set the configuration or provisioning files you wish to
+use Vault. Vault configuration is an extension of configuration's [variable expansion]({{< relref "../administration/configuration.md#variable-expansion" >}}) and follows the
+`$__vault{<argument>}` syntax.
+
+The argument to Vault consists of three parts separated by a colon:
+* The first part specifies which secrets engine should be used.
+* The second part specifies which secret should be accessed.
+* The third part specifies which field of that secret should be used.
+
+For example, if you place a Key/Value secret for the Grafana admin user in _secret/grafana/admin_defaults_
+the syntax for accessing it's _password_ field would be `$__vault{kv:secret/grafana/admin_defaults:password}`.
+
+### Secrets engines
+
+Vault supports many secrets engines which represents different methods for storing or generating secrets when requested by an
+authorized user. Grafana supports a subset of these which are most likely to be relevant for a Grafana installation.
+
+#### Key/Value
+
+Grafana supports Vault's [K/V version 2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) storage engine which
+is used to store and retrieve arbitrary secrets as `kv`. 
+
+```ini
+$__vault{kv:secret/grafana/smtp:username}
+```
+
+#### Databases
+
+The Vault [databases secrets engines](https://www.vaultproject.io/docs/secrets/databases) is a family of
+secret engines which shares a similar syntax and grants the user dynamic access to a database.
+You can use this both for setting up Grafana's own database access and for provisioning data sources.
+
+```ini
+$__vault{database:database/creds/grafana:username}
+```
+
+### Examples
+
+The following examples show you how to set your [configuration]({{< relref "../administration/configuration.md" >}}) or [provisioning]({{< relref "../administration/provisioning.md" >}}) files to use Vault to retrieve configuration values.
+
+#### Configuration
+
+The following is a partial example for using Vault to set up a Grafana configuration file's email and database credentials.
+Refer to [Configuration]({{< relref "../administration/configuration.md" >}}) for more information.
+
+```ini
+[smtp]
+enabled = true
+host = $__vault{kv:secret/grafana/smtp:hostname}:587
+user = $__vault{kv:secret/grafana/smtp:username}
+password = $__vault{kv:secret/grafana/smtp:password}
+
+[database]
+type = mysql
+host = mysqlhost:3306
+name = grafana
+user = $__vault{database:database/creds/grafana:username}
+password = $__vault{database:database/creds/grafana:password}
+```
+
+#### Provisioning
+
+The following is a full examples of a provisioning YAML file setting up a MySQL data source using Vault's
+database secrets engine.
+Refer to [Provisioning]({{< relref "../administration/provisioning.md" >}}) for more information.
+
+**provisioning/custom.yaml**
+
+```ini
+apiVersion: 1
+
+datasources:
+  - name: statistics
+    type: mysql
+    url: localhost:3306
+    database: stats
+    user: $__vault{database:database/creds/ro/stats:username}
+    secureJsonData:
+      password: $__vault{database:database/creds/ro/stats:password}
+```

docs/sources/menu.yaml

@@ -328,6 +328,8 @@
       link: /enterprise/white-labeling/
     - name: Usage insights
       link: /enterprise/usage-insights/
+    - name: Vault integration
+      link: /enterprise/vault/
     - name: License expiration
       link: /enterprise/license-expiration/
 - name: Plugins