Enable doc-validator for specific directories (#63524)
* Enable doc-validator for specific directories Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix one linting error to trigger CI Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update doc-validator to latest release Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update make-docs procedure Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Use doc-validator version from CI in local make target Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Revert to 1.11.0 Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * adds missing descriptions * Fix titles and headings Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix link formats Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix easy to resolve anchors Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Remove broken anchor link This anchor appears to have been broken for a long time. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Use doc-validator image with support for numbered anchors Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update make-docs procedure to support doc-validator 2.0.x Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix a bunch of broken anchors Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Ignore old whatsnew content Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Update doc-validator to v2.0.x and use reviewdog to report errors Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * removes broken links --------- Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Chris Moyer <chris.moyer@grafana.com>
This commit is contained in:
Jack Baldry
GitHub
+15
-15
@@ -12,26 +12,26 @@ weight: 700
|
||||
|
||||
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). These secrets are signed using a [secret key]({{< relref "../../configure-grafana/#secret_key" >}}) that you can change when you configure a new Grafana instance.
|
||||
Grafana encrypts these secrets before they are written to the database, by using a symmetric-key encryption algorithm called Advanced Encryption Standard (AES). These secrets are signed using a [secret key]({{< relref "../../configure-grafana#secret_key" >}}) that you can change when you configure a new Grafana instance.
|
||||
|
||||
> **Note:** Grafana v9.0 and newer use [envelope encryption](#envelope-encryption) by default, which adds a layer of indirection to the encryption process that introduces 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.
|
||||
For further details about how to operate a Grafana instance with envelope encryption, see the [Operational work]({{< relref "#operational-work" >}}) section.
|
||||
|
||||
> **Note:** In Grafana Enterprise, you can also [encrypt secrets in AES-GCM (Galois/Counter Mode)]({{< relref "#changing-your-encryption-mode-to-aes-gcm" >}}) instead of the default AES-CFB (Cipher FeedBack mode).
|
||||
|
||||
## Envelope encryption
|
||||
|
||||
> **Note:** Since Grafana v9.0, you can turn envelope encryption off by adding the feature toggle `disableEnvelopeEncryption` to your [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
|
||||
> **Note:** Since Grafana v9.0, you can turn envelope encryption off by adding the feature toggle `disableEnvelopeEncryption` to 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 [key management service (KMS) integration](#kms-integration).
|
||||
[Grafana configuration]({{< relref "../../configure-grafana#secret_key" >}}) or by [Encrypting your database with a key from a key management service (KMS)](#encrypting-your-database-with-a-key-from-a-key-management-service-kms).
|
||||
|
||||
### Implicit breaking change
|
||||
|
||||
Envelope encryption introduces an implicit breaking change to versions of Grafana prior to v9.0, because it changes how secrets stored in the Grafana database are encrypted. Grafana administrators can upgrade to Grafana v9.0 with no action required from the database encryption perspective, but must be extremely careful if they need to roll an upgrade back to Grafana v8.5 or earlier because secrets created or modified after upgrading to Grafana v9.0 can’t be decrypted by previous versions.
|
||||
|
||||
Grafana v8.5 implemented envelope encryption behind an optional feature toggle. Grafana administrators who need to downgrade to Grafana v8.5 can enable envelope encryption as a workaround by adding the feature toggle `envelopeEncryption` to the [Grafana configuration]({{< relref "../../configure-grafana/#feature_toggles" >}}).
|
||||
Grafana v8.5 implemented envelope encryption behind an optional feature toggle. Grafana administrators who need to downgrade to Grafana v8.5 can enable envelope encryption as a workaround by adding the feature toggle `envelopeEncryption` to the [Grafana configuration]({{< relref "../../configure-grafana#feature_toggles" >}}).
|
||||
|
||||
## Operational work
|
||||
|
||||
@@ -39,7 +39,7 @@ From the database encryption perspective, Grafana administrators can:
|
||||
|
||||
- [**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).
|
||||
- [**Re-encrypt data keys**](#re-encrypt-data-keys): re-encrypt data keys with a fresh key encryption key and a KMS integration.
|
||||
- [**Rotate data keys**](#rotate-data-keys): disable active data keys and stop using them for encryption in favor of a fresh one.
|
||||
|
||||
### Re-encrypt secrets
|
||||
@@ -49,19 +49,19 @@ You can re-encrypt secrets in order to:
|
||||
- Move already existing secrets' encryption forward from legacy to envelope encryption.
|
||||
- Re-encrypt secrets after a [data keys rotation](#rotate-data-keys).
|
||||
|
||||
To re-encrypt secrets, use the [Grafana CLI]({{< relref "../../../cli/" >}}) by running the `grafana cli admin secrets-migration re-encrypt` command or the `/encryption/reencrypt-secrets` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#roll-back-secrets" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
To re-encrypt secrets, use the [Grafana CLI]({{< relref "../../../cli" >}}) by running the `grafana cli admin secrets-migration re-encrypt` command or the `/encryption/reencrypt-secrets` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin#roll-back-secrets" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
|
||||
### Roll back secrets
|
||||
|
||||
You can roll back secrets encrypted with envelope encryption to legacy encryption. This might be necessary to downgrade to Grafana versions prior to v9.0 after an unsuccessful upgrade.
|
||||
|
||||
To roll back secrets, use the [Grafana CLI]({{< relref "../../../cli/" >}}) by running the `grafana cli admin secrets-migration rollback` command or the `/encryption/rollback-secrets` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#re-encrypt-secrets" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
To roll back secrets, use the [Grafana CLI]({{< relref "../../../cli" >}}) by running the `grafana cli admin secrets-migration rollback` command or the `/encryption/rollback-secrets` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin#re-encrypt-secrets" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
|
||||
### Re-encrypt data keys
|
||||
|
||||
You can re-encrypt data keys encrypted with a specific key encryption key (KEK). This allows you to either re-encrypt existing data keys with a new KEK version (see [KMS integration](#kms-integration) rotation) or to re-encrypt them with a completely different KEK.
|
||||
You can re-encrypt data keys encrypted with a specific key encryption key (KEK). This allows you to either re-encrypt existing data keys with a new KEK version or to re-encrypt them with a completely different KEK.
|
||||
|
||||
To re-encrypt data keys, use the [Grafana CLI]({{< relref "../../../cli/" >}}) by running the `grafana cli admin secrets-migration re-encrypt-data-keys` command or the `/encryption/reencrypt-data-keys` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#re-encrypt-data-encryption-keys" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
To re-encrypt data keys, use the [Grafana CLI]({{< relref "../../../cli" >}}) by running the `grafana cli admin secrets-migration re-encrypt-data-keys` command or the `/encryption/reencrypt-data-keys` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin#re-encrypt-data-encryption-keys" >}}). It's safe to run more than once, more recommended under maintenance mode.
|
||||
|
||||
### Rotate data keys
|
||||
|
||||
@@ -73,7 +73,7 @@ New data keys for encryption operations are generated on demand.
|
||||
> secrets still encrypted with them. To completely stop using
|
||||
> rotated data keys for both encryption and decryption, see [secrets re-encryption](#re-encrypt-secrets).
|
||||
|
||||
To rotate data keys, use the `/encryption/rotate-data-keys` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin/#rotate-data-encryption-keys" >}}). It's safe to call more than once, more recommended under maintenance mode.
|
||||
To rotate data keys, use the `/encryption/rotate-data-keys` endpoint of the Grafana [Admin API]({{< relref "../../../developers/http_api/admin#rotate-data-encryption-keys" >}}). It's safe to call more than once, more recommended under maintenance mode.
|
||||
|
||||
## Encrypting your database with a key from a key management service (KMS)
|
||||
|
||||
@@ -83,10 +83,10 @@ You can choose to encrypt secrets stored in the Grafana database using a key fro
|
||||
|
||||
Grafana integrates with the following key management services:
|
||||
|
||||
- [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/" >}})
|
||||
- [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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user