mirror of
https://github.com/grafana/grafana.git
synced 2025-08-06 02:29:33 +08:00
Docs: Refactor encryption docs (#44718)
* Docs: Refactor encryption docs * Rename enterprise encr * Remove envelope encr page * combine database encryption sections * fix reference * Fix link Co-authored-by: Mitchel Seaman <mitchel.seaman@gmail.com>
This commit is contained in:
Tania B
35
docs/sources/enterprise/enterprise-encryption/_index.md
Normal file
35
docs/sources/enterprise/enterprise-encryption/_index.md
Normal file
@ -0,0 +1,35 @@
|
||||
+++
|
||||
title = "Enterprise database encryption"
|
||||
description = "Grafana Enterprise database encryption"
|
||||
keywords = ["grafana", "enterprise", "database", "encryption", "documentation"]
|
||||
aliases = [""]
|
||||
weight = 130
|
||||
+++
|
||||
|
||||
# Grafana Enterprise database encryption
|
||||
|
||||
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.
|
||||
|
||||
## Encrypting your database with a key from a Key Management System (KMS)
|
||||
|
||||
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 "/using-aws-kms-to-encrypt-database-secrets.md" >}})
|
||||
- [Azure Key Vault]({{< relref "/using-azure-key-vault-to-encrypt-database-secrets.md" >}})
|
||||
- [Google Cloud KMS]({{< relref "/using-google-cloud-kms-to-encrypt-database-secrets.md" >}})
|
||||
- [Hashicorp Key Vault]({{< relref "/using-hashicorp-key-vault-to-encrypt-database-secrets.md" >}})
|
||||
|
||||
Refer to [Database encryption]({{< relref "../../administration/database-encryption.md" >}}) to learn more about how Grafana encrypts secrets in the database.
|
||||
|
||||
## 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 "../enterprise-configuration.md#securityencryption" >}}).
|
||||
@ -0,0 +1,83 @@
|
||||
+++
|
||||
title = "AMS KMS"
|
||||
description = "Using AWS KMS to encrypt database secrets"
|
||||
keywords = ["grafana", "AWS KMS integration"]
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
# Using AWS KMS to encrypt database secrets
|
||||
|
||||
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 "../../administration/configuration/#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 "../../administration/envelope-encryption.md" >}}).
|
||||
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.
|
||||
@ -0,0 +1,81 @@
|
||||
+++
|
||||
title = "Azure Key Vault"
|
||||
description = "Using Azure Key Vault to encrypt database secrets"
|
||||
keywords = ["grafana", "Azure key vault"]
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
# Using Azure Key Vault to encrypt database secrets
|
||||
|
||||
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 "../../administration/configuration/#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 "../../administration/envelope-encryption.md" >}}).
|
||||
|
||||
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.
|
||||
@ -0,0 +1,70 @@
|
||||
+++
|
||||
title = "Google Cloud KMS"
|
||||
description = "Using Google Cloud KMS to encrypt database secrets"
|
||||
keywords = ["grafana", "Google Cloud KMS integration"]
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
# Using Google Cloud KMS to encrypt database secrets
|
||||
|
||||
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 "../../administration/configuration/#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 "../../administration/envelope-encryption.md" >}}).
|
||||
|
||||
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.
|
||||
@ -0,0 +1,77 @@
|
||||
+++
|
||||
title = "Hashicorp Vault"
|
||||
description = "Using Hashicorp Vault to encrypt database secrets"
|
||||
keywords = ["grafana", "Hashicorp Vault integration"]
|
||||
weight = 3
|
||||
+++
|
||||
|
||||
# Using Google Cloud KMS to encrypt database secrets
|
||||
|
||||
You can use an encryption key from Google Cloud Key Management Service 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 "../../administration/configuration/#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 "../../administration/envelope-encryption.md" >}}).
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user