From a02c6f2d36bb7d64bdb66b2c5126c712d38ebdc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Agn=C3=A8s=20Toulet?= <35176601+AgnesToulet@users.noreply.github.com> Date: Wed, 1 Jul 2020 08:40:58 +0200 Subject: [PATCH] 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 * 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 Co-authored-by: Leonard Gram Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> --- docs/sources/administration/configuration.md | 14 +- docs/sources/enterprise/_index.md | 1 + .../enterprise/enterprise-configuration.md | 30 ++++ docs/sources/enterprise/vault.md | 139 ++++++++++++++++++ docs/sources/menu.yaml | 2 + 5 files changed, 182 insertions(+), 4 deletions(-) create mode 100644 docs/sources/enterprise/vault.md diff --git a/docs/sources/administration/configuration.md b/docs/sources/administration/configuration.md index 2d1ed8b699b..ff87fbd9ab0 100644 --- a/docs/sources/administration/configuration.md +++ b/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 `$__{}` or `${}`, 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" >}}).
diff --git a/docs/sources/enterprise/_index.md b/docs/sources/enterprise/_index.md index c22b0dfe7d9..7f976360846 100755 --- a/docs/sources/enterprise/_index.md +++ b/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 diff --git a/docs/sources/enterprise/enterprise-configuration.md b/docs/sources/enterprise/enterprise-configuration.md index 929056acff1..110a0d961fe 100644 --- a/docs/sources/enterprise/enterprise-configuration.md +++ b/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. \ No newline at end of file diff --git a/docs/sources/enterprise/vault.md b/docs/sources/enterprise/vault.md new file mode 100644 index 00000000000..55c89eb2e7d --- /dev/null +++ b/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{}` 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} +``` diff --git a/docs/sources/menu.yaml b/docs/sources/menu.yaml index d7239fca3a6..ec02031f65c 100644 --- a/docs/sources/menu.yaml +++ b/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