public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Setup refactor (#49739)

Browse Source 
* builds out refactored setup topics

* Automatically fix some relrefs with mv-manager

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Use refs for tutorials content which is outside of this repository

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Manually fix complicated relrefs

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* consolidates team sync and db encryption topics

* Fix relrefs

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* updates setup index file

* Convert TOML to YAML

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Add current alias for new alerting content

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Add current aliases to new setup-grafana and configure-security pages

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update docs/sources/setup-grafana/configure-grafana/_index.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.com>

* moves saml docs, updates order in TOC

* Manually fix relrefs

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* added usage insights topics, adjusted weights

* corrected relrefs

* Fix relrefs broken in rebase

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: Torkel Ödegaard <torkel@grafana.com>
This commit is contained in:
Christopher Moyer
2022-06-02 11:57:22 -05:00
committed by GitHub
co-authored by Torkel Ödegaard Jack Baldry
parent 104c4a7630
commit a568d421f8
345 changed files with 1557 additions and 1733 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/setup-grafana/configure-security/configure-database-encryption/_index.md
+126
View File
@@ -0,0 +1,126 @@
---
aliases:
- /docs/grafana/latest/administration/database-encryption/
- /docs/grafana/latest/enterprise/enterprise-encryption/
- /docs/grafana/latest/setup-grafana/configure-security/configure-database-encryption/
description: If you have a Grafana Enterprise license, you can integrate with a variety
of key management system providers.
title: Configure database encryption
weight: 700
---
# Configure database encryption
Grafana’s database contains secrets, which are used to query data sources, send alert notifications and perform other functions within Grafana.
Grafana encrypts these secrets before they are written to the database, by using a symmetric-key encryption algorithm called Advanced Encryption Standard (AES), and using a [secret key]({{< relref "../../configure-grafana/#secret_key" >}}) that you can change when you configure a new Grafana instance.
Since Grafana v9.0, it uses [envelope encryption](#envelope-encryption) by default, which adds a layer of indirection to the
encryption process that represents an [**implicit breaking change**](#implicit-breaking-change) for older versions of Grafana.
For further details about how to operate a Grafana instance with envelope encryption, see the [Operational work]({{< relref "./#operational-work" >}}) section below.
> **Note:** In Grafana Enterprise, you can also choose to [encrypt secrets in AES-GCM mode]({{< relref "#changing-your-encryption-mode-to-aes-gcm" >}}) instead of AES-CFB.
# Envelope encryption
> **Note:** Since Grafana v9.0, you can turn it off by adding the term `disableEnvelopeEncryption` to the list of
> feature toggles in your [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
Instead of encrypting all secrets with a single key, Grafana uses a set of keys called data encryption keys (DEKs) to
encrypt them. These data encryption keys are themselves encrypted with a single key encryption key (KEK), configured
through the `secret_key` attribute in your
[Grafana configuration]({{< relref "../../configure-grafana/#secret_key" >}}) or with a
[KMS integration](#kms-integration).
## Implicit breaking change
As stated above, envelope encryption represents an implicit breaking change because it changes the way secrets stored
in the Grafana database are encrypted. That means Grafana administrators will be able to transition to Grafana v9.0
with no action required from the database encryption perspective, but will need to be extremely careful if they need
to roll back to a previous version (e.g. Grafana v8.5) after being updated, because secrets created or modified after upgrade
the update to Grafana v9.0 won't be decryptable in previous versions.
Fortunately though, envelope encryption was added in Grafana v8.3 behind a feature toggle. So, in case of emergency,
Grafana administrators will be able to downgrade up to Grafana v8.3 and enable envelope encryption as a workaround.
> **Note:** In Grafana releases between v8.3 and v8.5, you can turn envelope encryption on by adding the term
> `envelopeEncryption` to the list of feature toggles in your
> [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
# Operational work
From the database encryption perspective, there are several operations that Grafana administrator may want to perform:
- [**Re-encrypt secrets**](#re-encrypt-secrets): re-encrypt secrets with envelope encryption and a fresh data key.
- [**Roll back secrets**](#roll-back-secrets): decrypt secrets encrypted with envelope encryption and re-encrypt them with legacy encryption.
- [**Re-encrypt data keys**](#re-encrypt-data-keys): re-encrypt data keys with a fresh key encryption key and a [KMS integration](#kms-integration).
- [**Rotate data keys**](#rotate-data-keys): disable active data keys and stop using them for encryption in favor of a fresh one.
Find more details about each of those below.
## Re-encrypt secrets
Secrets re-encryption can be performed when a Grafana administrator wants to either:
- Move forward already existing secrets' encryption from legacy to envelope encryption.
- Re-encrypt secrets after a [data keys rotation](#rotate-data-keys).
> **Note:** This operation is available through Grafana CLI by running `grafana-cli admin secrets-migration re-encrypt`
> command. It's safe to run more than once. Recommended to run under maintenance mode.
## Roll back secrets
Used to roll back secrets encrypted with envelope encryption to legacy encryption. It can be used to downgrade to
a Grafana version earlier than Grafana v9.0 after an unsuccessful upgrade.
> **Note:** This operation is available through Grafana CLI by running `grafana-cli admin secrets-migration rollback`
> command. It's safe to run more than once. Recommended to run under maintenance mode.
## Re-encrypt data keys
Used to re-encrypt data keys encrypted with a specific key encryption key (KEK). It can be used to either re-encrypt
existing data keys with a new key encryption key version (see [KMS integration](#kms-integration) rotation) or to
re-encrypt them with a completely different key encryption key.
> **Note:** This operation is available through Grafana CLI by running `grafana-cli admin secrets-migration re-encrypt-data-keys`
> command. It's safe to run more than once. Recommended to run under maintenance mode.
## Rotate data keys
Data keys rotation can be performed to disable the active data key and therefore stop using them for encryption operations.
For high-availability setups, you may need to wait until the data keys cache's TTL (time-to-live) expires to ensure that all
rotated data keys are no longer being used for encryption operations.
New data keys for encryption operations are generated on-demand.
> **Note:** It does not imply secrets re-encryption. Therefore, rotated data keys will continue being used to decrypt
> those secrets still encrypted with it. Look at [secrets re-encryption](#re-encrypt-secrets) to completely stop using
> rotated data keys for both encryption and decryption.
> **Note:** This operation is available through Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#rotate-data-encryption-keys" >}}).
> It's safe to run more than once.
## Encrypting your database with a key from a Key Management System (KMS)
If you are using Grafana Enterprise, you can integrate with a key management system (KMS) provider, and change Grafana’s cryptographic mode of operation from AES-CFB to AES-GCM.
You can choose to encrypt secrets stored in the Grafana database using a key from a KMS, which is a secure central storage location that is designed to help you to create and manage cryptographic keys and control their use across many services. When you integrate with a KMS, Grafana does not directly store your encryption key. Instead, Grafana stores KMS credentials and the identifier of the key, which Grafana uses to encrypt the database.
Grafana integrates with the following key management systems:
- [AWS KMS]({{< relref "encrypt-secrets-using-aws-kms/" >}})
- [Azure Key Vault]({{< relref "encrypt-secrets-using-azure-key-vault/" >}})
- [Google Cloud KMS]({{< relref "encrypt-secrets-using-google-cloud-kms/" >}})
- [Hashicorp Key Vault]({{< relref "encrypt-secrets-using-hashicorp-key-vault/" >}})
## Changing your encryption mode to AES-GCM
Grafana encrypts secrets using Advanced Encryption Standard in Cipher
FeedBack mode (AES-CFB). You might prefer to use AES in Galois/Counter
Mode (AES-GCM) instead, to meet your company’s security requirements or
in order to maintain consistency with other services.
To change your encryption mode, update the `algorithm` value in the
`[security.encryption]` section of your Grafana configuration file.
For details, refer to [Enterprise configuration]({{< relref "../../configure-grafana/enterprise-configuration/#securityencryption" >}}).
docs/sources/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-aws-kms.md
+85
View File
@@ -0,0 +1,85 @@
---
aliases:
- /docs/grafana/latest/enterprise/enterprise-encryption/using-aws-kms-to-encrypt-database-secrets/
- /docs/grafana/latest/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-aws-kms/
description: Learn how to use AWS KMS to encrypt secrets in the Grafana database.
title: Encrypt database secrets using AWS KMS
weight: 300
---
# Encrypt database secrets using AWS KMS
You can use an encryption key from AWS Key Management Service to encrypt secrets in the Grafana database.
**Prerequisites:**
- An AWS account with permission to view and create KMS keys and programmatic credentials to access those keys
- Access to the Grafana [configuration]({{< relref "../../configure-grafana/#config-file-locations" >}}) file
1. Create a symmetric API key either from the AWS Management Console or by using the AWS KMS API.
<br><br>For detailed instructions, refer to [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html).
2. Retrieve the Key ID.
<br><br>In AWS terms, this can be a key ID, a key ARN (Amazon Resource Name), an alias name, or an alias ARN. For more information about how to retrieve a key ID from AWS, refer to [Finding the key ID and key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html).
3. Create a [programmatic credential](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) (access key ID and secret access key), which has permission to view the key that you created.
<br><br>In AWS, you can control access to your KMS keys by using [key policies](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html), [IAM policies](https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html), and [grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html). You can also create [temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html), which must provide a session token along with an access key ID and a secret access key.
4. From within Grafana, turn on [envelope encryption]({{< relref "./#envelope-encryption" >}}).
5. Add your AWS KMS details to the Grafana configuration file; depending on your operating system, it is usually named `grafana.ini`:
<br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.awskms.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.
<br><br>b. Fill in the section with the following values:
<br>
- `key_id`: a reference to a key stored in the KMS. This can be a key ID, a key Amazon Resource Name (ARN), an alias name, or an alias ARN. If you are using an alias, use the prefix `alias/`. To specify a KMS key in a different AWS account, use its ARN or alias. For more information about how to retrieve a key ID from AWS, refer to [Finding the key ID and key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html).<br>
| `key_id` option | Example value |
| --- | --- |
| Key ID | `1234abcd-12ab-34cd-56ef-1234567890ab` |
| Key ARN | `arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab` |
| Alias name | `alias/ExampleAlias` |
| Alias ARN | `arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias` |
- `access_key_id`: The AWS Access Key ID that you previously generated.
- `secret_access_key`: The AWS Secret Access Key you previously generated.
- `region`: The AWS region where you created the KMS key. The region is contained in the key’s ARN. For example: `arn:aws:kms:*us-east-2*:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`
An example of an AWS KMS provider section in the `grafana.ini` file is as follows:
```
# AWS key management service provider setup
;[security.encryption.awskms.example-encryption-key]
# Reference to a KMS key - either key ID, key ARN, alias name, or ARN
;key_id = 1234abcd-12ab-34cd-56ef-1234567890ab
# AWS access key ID
;access_key_id = AKIAIOSFODNN7EXAMPLE
# AWS secret access key
;secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# AWS region, for example eu-north-1
;region = eu-north-1
```
6. Update the `[security]` section of the `grafana.ini` configuration file with the new Encryption Provider key that you created:
```
[security]
# previous encryption key, used for legacy alerts, decrypting existing secrets or used as default provider when external providers are not configured
secret_key = AaaaAaaa
# encryption provider key in the format <PROVIDER>.<KEY_NAME>
encryption_provider = awskms.example-encryption-key
# list of configured key providers, space separated
available_encryption_providers = awskms.example-encryption-key
```
**> Note:** The encryption key that is stored in the `secret_key` field is still used by Grafana’s legacy alerting system to encrypt secrets, for decrypting existing secrets, or it is used as the default provider when external providers are not configured. Do not change or remove that value when adding a new KMS provider.
7. [Restart Grafana](https://grafana.com/docs/grafana/latest/installation/restart-grafana/).
8. (Optional) From the command line and the root directory of Grafana, re-encrypt all of the secrets within the Grafana database with the new key using the following command:
`grafana-cli admin secrets-migration re-encrypt`
If you do not re-encrypt existing secrets, then they will remain encrypted by the previous encryption key. Users will still be able to access them.
**> Note:** This process could take a few minutes to complete, depending on the number of secrets (such as data sources or alert notification channels) in your database. Users might experience errors while this process is running, and alert notifications might not be sent.
**> Note:** If you are updating this encryption key during the initial setup of Grafana before any data sources, alert notification channels, or dashboards have been created, then this step is not necessary because there are no secrets in Grafana to migrate.
docs/sources/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-azure-key-vault.md
+83
View File
@@ -0,0 +1,83 @@
---
aliases:
- /docs/grafana/latest/enterprise/enterprise-encryption/using-azure-key-vault-to-encrypt-database-secrets/
- /docs/grafana/latest/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-azure-key-vault/
description: Learn how to use Azure Key Vault to encrypt secrets in the Grafana database.
title: Encrypt database secrets using Azure Key Vault
weight: 400
---
# Encrypt database secrets using Azure Key Vault
You can use an encryption key from Azure Key Vault to encrypt secrets in the Grafana database.
**Prerequisites:**
- An Azure account with permission to view and create Key Vault keys and programmatic credentials to access those keys
- Access to the Grafana [configuration]({{< relref "../../configure-grafana/#config-file-locations" >}}) file
1. [Create a vault](https://docs.microsoft.com/en-us/azure/key-vault/general/quick-create-portal#create-a-vault).
2. Create a key in the **Key Vault** with the name that you want by using **RSA** as the type and `2048` as the size with encrypt and decrypt permissions.
3. [Register an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application) and generate a client secret for it.
4. [Assign a Key Vault access policy](https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal) for the key vault that you created:
5. In the Key Permissions section, set encrypt and decrypt permissions, and click **Save**.
6. From within Grafana, turn on [envelope encryption]({{< relref "./" >}}).
7. Add your Azure Key Vault details to the Grafana configuration file; depending on your operating system, is usually named `grafana.ini`:
<br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.azurekv.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.
<br><br>b. Fill in the section with the following values:
<br>
- `tenant_id`: the **Directory ID** (tenant) from the application that you registered.
- `client_id`: the **Application ID** (client) from the application that you registered.
- `client_secret`: the VALUE of the secret that you generated in your app. (Don't use the Secret ID).
- `key_id`: the key name that you created in the key vault.
- `vault_uri`: the URL of your key vault.
An example of an Azure Key Vault provider section in the `grafana.ini` file is as follows:
```
# Azure Key Vault provider setup
;[security.encryption.azurekv.example-encryption-key]
# Azure Application directory ID (tenant)
tenant_id = 1234abcd-12ab-34cd-56ef-1234567890ab
# Azure Application application ID (client).
client_id = 1356dfgh-12ab-34cd-56ef-3322114455cc
# Azure Application client secret.
client_secret = FbE4X~4Jq45ERKxx823Aheb9plBjQqHHe81Sc
# Azure Key Vault key name.
key_id = mysecretkey
# Azure Key Vault uri.
vault_uri = https://my-vault-name.vault.azure.net
```
8. Update the `[security]` section of the `grafana.ini` configuration file with the new Encryption Provider key that you created:
```
[security]
# previous encryption key, used for legacy alerts, decrypting existing secrets or used as default provider when external providers are not configured
secret_key = AaaaAaaa
# encryption provider key in the format <PROVIDER>.<KEY-NAME>
encryption_provider = azurekv.example-encryption-key
# list of configured key providers, space separated
available_encryption_providers = azurekv.example-encryption-key
```
**> Note:** The encryption key stored in the `secret_key` field is still used by Grafana’s legacy alerting system to encrypt secrets. Do not change or remove that value.
9. [Restart Grafana](https://grafana.com/docs/grafana/latest/installation/restart-grafana/).
10. (Optional) From the command line and the root directory of Grafana Enterprise, re-encrypt all of the secrets within the Grafana database with the new key using the following command:
`grafana-cli admin secrets-migration re-encrypt`
If you do not re-encrypt existing secrets, then they will remain encrypted by the previous encryption key. Users will still be able to access them.
**> Note:** This process could take a few minutes to complete, depending on the number of secrets (such as data sources or alert notification channels) in your database. Users might experience errors while this process is running, and alert notifications might not be sent.
**> Note:** If you are updating this encryption key during the initial setup of Grafana before any data sources, alert notification channels, or dashboards have been created, then this step is not necessary because there are no secrets in Grafana to migrate.
docs/sources/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-google-cloud-kms.md
+72
View File
@@ -0,0 +1,72 @@
---
aliases:
- /docs/grafana/latest/enterprise/enterprise-encryption/using-google-cloud-kms-to-encrypt-database-secrets/
- /docs/grafana/latest/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-google-cloud-kms/
description: Learn how to use Google Cloud KMS to encrypt secrets in the Grafana database.
title: Encrypt database secrets using Google Cloud KMS
weight: 100
---
# Encrypt database secrets using Google Cloud KMS
You can use an encryption key from Google Cloud Key Management Service to encrypt secrets in the Grafana database.
**Prerequisites:**
- A Google Cloud account with permission to list and create KMS keys and service accounts to access those keys
- Access to the Grafana [configuration]({{< relref "../../configure-grafana/#config-file-locations" >}}) file
1. [Create a key ring](https://cloud.google.com/kms/docs/creating-keys#kms-create-key-ring-console) in Google Cloud KMS.
2. [Create a symmetric encryption key](https://cloud.google.com/kms/docs/creating-keys#create_a_key) in the key ring.
3. [Create a service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating) and assign it a role: it can be a predefined role or custom role with permissions to encrypt and decrypt secrets with Key Management Service.
4. [Create a service account key and save its JSON file](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) to you computer, for example, as `~/.config/gcloud/sample-project-credentials.json`.
5. From within Grafana, turn on [envelope encryption]({{< relref "./#envelope-encryption" >}}).
6. Add your Google Cloud KMS details to the Grafana configuration file; depending on your operating system, is usually named `grafana.ini`:
<br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.azurekv.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.
<br><br>b. Fill in the section with the following values:
<br>
- `key_id`: encryption key ID, refer to [Getting the ID for a Key](https://cloud.google.com/kms/docs/getting-resource-ids#getting_the_id_for_a_key_and_version).
- `credentials_file`: full path to service account key JSON file on your computer.
An example of a Google Cloud KMS provider section in the `grafana.ini` file is as follows:
```
# Example of Google Cloud KMS provider setup
;[security.encryption.googlekms.example-encryption-key]
# Google Cloud KMS key ID
key_id = 1234abcd-12ab-34cd-56ef-1234567890ab
# Full path to a JSON file with a service account key
credentials_file = ~/.config/gcloud/sample-project-credentials.json
```
7. Update the `[security]` section of the `grafana.ini` configuration file with the new Encryption Provider key that you created:
```
[security]
# previous encryption key, used for legacy alerts, decrypting existing secrets or used as default provider when external providers are not configured
secret_key = AaaaAaaa
# encryption provider key in the format <PROVIDER>.<KEY-NAME>
encryption_provider = googlekms.example-encryption-key
# list of configured key providers, space separated
available_encryption_providers = googlekms.example-encryption-key
```
**> Note:** The encryption key stored in the `secret_key` field is still used by Grafana’s legacy alerting system to encrypt secrets. Do not change or remove that value.
8. [Restart Grafana](https://grafana.com/docs/grafana/latest/installation/restart-grafana/).
9. (Optional) From the command line and the root directory of Grafana Enterprise, re-encrypt all of the secrets within the Grafana database with the new key using the following command:
`grafana-cli admin secrets-migration re-encrypt`
If you do not re-encrypt existing secrets, then they will remain encrypted by the previous encryption key. Users will still be able to access them.
**> Note:** This process could take a few minutes to complete, depending on the number of secrets (such as data sources or alert notification channels) in your database. Users might experience errors while this process is running, and alert notifications might not be sent.
**> Note:** If you are updating this encryption key during the initial setup of Grafana before any data sources, alert notification channels, or dashboards have been created, then this step is not necessary because there are no secrets in Grafana to migrate.
docs/sources/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-hashicorp-key-vault.md
+79
View File
@@ -0,0 +1,79 @@
---
aliases:
- /docs/grafana/latest/enterprise/enterprise-encryption/using-hashicorp-key-vault-to-encrypt-database-secrets/
- /docs/grafana/latest/setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-hashicorp-key-vault/
description: Learn how to use Hashicorp Vault to encrypt secrets in the Grafana database.
title: Encrypt database secrets using Hashicorp Vault
weight: 200
---
# Encrypt database secrets using Hashicorp Vault
You can use an encryption key from Hashicorp Vault to encrypt secrets in the Grafana database.
**Prerequisites:**
- Permissions to manage Hashicorp Vault to enable secrets engines and issue tokens.
- Access to the Grafana [configuration]({{< relref "../../configure-grafana/#config-file-locations" >}}) file
1. [Enable the transit secrets engine](https://www.vaultproject.io/docs/secrets/transit#setup) in Hashicorp Vault.
2. [Create a named encryption key](https://www.vaultproject.io/docs/secrets/transit#setup).
3. [Create a periodic service token](https://learn.hashicorp.com/tutorials/vault/tokens#periodic-service-tokens).
4. From within Grafana, turn on [envelope encryption]({{< relref "./#envelop-encryption" >}}).
5. Add your Hashicorp Vault details to the Grafana configuration file; depending on your operating system, is usually named `grafana.ini`:
<br><br>a. Add a new section to the configuration file, with a name in the format of `[security.encryption.hashicorpvault.<KEY-NAME>]`, where `<KEY-NAME>` is any name that uniquely identifies this key among other provider keys.
<br><br>b. Fill in the section with the following values:
<br>
- `token`: a periodic service token used to authenticate within Hashicorp Vault.
- `url`: URL of the Hashicorp Vault server.
- `transit_engine_path`: mount point of the transit engine.
- `key_ring`: name of the encryption key.
- `token_renewal_interval`: specifies how often to renew token; should be less than the `period` value of a periodic service token.
An example of a Hashicorp Vault provider section in the `grafana.ini` file is as follows:
```
# Example of Hashicorp Vault provider setup
;[security.encryption.hashicorpvault.example-encryption-key]
# Token used to authenticate within Vault. We suggest to use periodic tokens: more on token types https://www.vaultproject.io/docs/concepts/tokens#service-tokens
;token =
# Location of the Hashicorp Vault server
;url = http://localhost:8200
# Mount point of the transit secret engine
;transit_engine_path = transit
# Key ring name
;key_ring = grafana-encryption-key
# Specifies how often to check if a token needs to be renewed, should be less than a token's period value
token_renewal_interval = 5m
```
6. Update the `[security]` section of the `grafana.ini` configuration file with the new Encryption Provider key that you created:
```
[security]
# previous encryption key, used for legacy alerts, decrypting existing secrets or used as default provider when external providers are not configured
secret_key = AaaaAaaa
# encryption provider key in the format <PROVIDER>.<KEY-NAME>
encryption_provider = hashicorpvault.example-encryption-key
# list of configured key providers, space separated
available_encryption_providers = hashicorpvault.example-encryption-key
```
**> Note:** The encryption key stored in the `secret_key` field is still used by Grafana’s legacy alerting system to encrypt secrets. Do not change or remove that value.
7. [Restart Grafana](https://grafana.com/docs/grafana/latest/installation/restart-grafana/).
8. (Optional) From the command line and the root directory of Grafana Enterprise, re-encrypt all of the secrets within the Grafana database with the new key using the following command:
`grafana-cli admin secrets-migration re-encrypt`
If you do not re-encrypt existing secrets, then they will remain encrypted by the previous encryption key. Users will still be able to access them.
**> Note:** This process could take a few minutes to complete, depending on the number of secrets (such as data sources or alert notification channels) in your database. Users might experience errors while this process is running, and alert notifications might not be sent.
**> Note:** If you are updating this encryption key during the initial setup of Grafana before any data sources, alert notification channels, or dashboards have been created, then this step is not necessary because there are no secrets in Grafana to migrate.
docs/sources/setup-grafana/configure-security/configure-database-encryption/integrate-with-hashicorp-vault.md
+138
View File
@@ -0,0 +1,138 @@
---
aliases:
- /docs/grafana/latest/enterprise/vault/
- /docs/grafana/latest/setup-grafana/configure-security/configure-database-encryption/integrate-with-hashicorp-vault/
description: Learn how to integrate Grafana with Hashicorp Vault so that you can use
secrets for configuration and provisioning.
title: Integrate Grafana with Hashicorp Vault
weight: 500
---
# Integrate Grafana with Hashicorp Vault
If you manage your secrets with [Hashicorp Vault](https://www.hashicorp.com/products/vault), you can use them for [Configuration]({{< relref "../../configure-grafana/" >}}) and [Provisioning]({{< relref "../../../administration/provisioning/" >}}).
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../enterprise/" >}}) and [Grafana Cloud Advanced]({{< ref "/docs/grafana-cloud" >}}).
> **Note:** If you have Grafana [set up for high availability]({{< relref "../../set-up-for-high-availability/" >}}), 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 "../../configure-grafana/#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 "../../configure-grafana/" >}}) or [provisioning]({{< relref "../../../administration/provisioning/" >}}) 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 "../../configure-grafana/" >}}) 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/" >}}) 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}
```