How Grafana encrypts data source secrets and when to plan for its keys
Grafana protects the passwords and tokens it stores for data sources by encrypting them before they are written to its database, so a copy of the database alone does not expose those credentials in plain text. The protection is only as strong as the key that unlocks it. In practice, the security team's question is less about the cipher and more about where the key lives, who can read it, and what happens to the stored secrets when that key has to change. Grafana uses envelope encryption, in which a data key encrypts the secret values and that data key is itself protected by a key derived from the instance's configuration, principally the secret_key setting in the [security] section of grafana.ini. Anyone who can read that configuration file, the environment that supplies it, or a backup containing both the database and the configuration can recover the secrets.
That makes key custody the decision to settle first. Confirm where secret_key is set in your deployment (a file, an environment variable or a secret store in your container platform), who can read it, whether it is excluded from backups stored apart from the database, and how it is injected into each replica of a high-availability setup. Changing the key is not a simple restart. Stored secrets must be re-encrypted under the new key in a planned step, so the procedure, its rollback and a verified backup belong in the change plan. Grafana Enterprise documents key management service options that move key custody outside the configuration file, and rotation of data keys is a separate operation from changing secret_key. Because exact behavior, supported commands and option availability differ between releases, confirm the procedure against the Grafana version you run and the Enterprise documentation for your license before you design around it.
Key sources and settings to compare before you deploy
This table compares the ways to supply Grafana's encryption key, from a value in the configuration file to KMS-backed options described for Grafana Enterprise. Read each row for when the option fits and what your team must store, rotate and back up. Whichever option you choose, the key must be preserved separately from the database, because encrypted data source secrets cannot be recovered without it.
| Option | When it fits | What the operator must own | What to confirm |
|---|---|---|---|
| secret_key in the configuration file | A single virtual machine with a small operations team and simple host access controls | File permissions, a secure backup of the key value, and a documented rotation procedure | Exact configuration section and key name in the current installation docs |
| Same value as an environment variable at container start | Container platforms where configuration is injected at runtime rather than baked into images | Keeping the value out of images and version control, and the injection pipeline itself | Environment variable name and whether it overrides the configuration file |
| Value injected from an external secret store at start | Regulated environments that need evidence of who could read or change the key | Access policies on the secret store, rotation schedule, audit log retention and key backup | Whether your secret store integration pattern is supported for this setting |
| KMS-backed key options | Organizations that need key custody handled by a managed key service and evidence of key use | Cloud or KMS key policies, key access logging, Enterprise licensing and key lifecycle | Edition that includes the feature, supported KMS providers and current setup steps on the licensing page and docs |
| Key changes after deployment | Any option, when a key must be replaced after exposure, staff change or policy | An inventory of stored data source credentials and a tested re-encryption procedure | Current re-encryption command and whether a restart or maintenance window is required |
| Key backup relative to database backup | Every option, because encrypted secrets are stored in the database | A key copy kept apart from database backups, with restore tested together with the database | Whether restoring a database without its matching key is detectable in your version |
| Audit evidence for key handling | Assessments that ask who could access or change the key and when | Records of key creation, access grants, rotation dates and restore tests | What Grafana itself logs about key changes in your edition |
What the secret_key protects and what losing it costs
Grafana uses the secret_key setting to encrypt credentials it stores in its database. The same key guards backups, every node in a shared cluster and any copy an attacker might take, so its handling shapes your restore, failover and incident plans.
Data that depends on the key
Grafana encrypts stored secrets such as data source passwords, API tokens and similar credentials before writing them to the database. The secret_key value is the material that protects them. Before go-live, list every data source that stores a credential in Grafana, then confirm which of them are saved as encrypted secrets in your instance rather than in files you manage separately.
Losing the key
If the key is lost or changed without a plan, stored secrets may become unreadable, and data sources that depend on them stop working until someone re-enters the credentials. A database restore is not enough on its own. Store the key in a secrets manager or sealed vault with its own access log, and rehearse a restore that includes the key, so recovery does not depend on one administrator's notes.
Leaked key and database copy
Anyone who holds a copy of the Grafana database and the secret_key can recover the stored credentials. Backups, database snapshots and developer copies therefore carry the same exposure as the live system. Confirm who can read database backups, where the key is kept outside the database and whether a key rotation procedure exists for the case where a copy or key has been exposed.
Matching keys across HA nodes
Grafana high availability runs two or more active-active servers behind a load balancer, and they share one MySQL or PostgreSQL database. Every node must use the same secret_key, or nodes cannot decrypt what the others wrote. Check the configuration on each node after changes, and include the key in the rollout checklist for new nodes so a replacement server does not start with a different value.
What the key does not protect
The secret_key does not cover credentials placed in provisioning files, environment variables or dashboard JSON, and it does not protect traffic leaving Grafana toward data sources. Provisioning files and container variables must be secured by their own controls, such as file permissions, a secrets store or orchestrator secrets. Review these locations separately, because encrypting the database leaves them readable to anyone with access to the host or repository.
Setting the secret_key before the first production start
This sequence fixes the encryption key Grafana uses for data source credentials before any real data is stored, so the key is consistent across nodes, survives restarts and restores, and is verified before production use.
Generate and store the key in a secret store
The platform or security team generates a long, random value using a cryptographically secure generator approved by your security policy, then records it in your organization's secret store with restricted read access and a named owner. Do not type the key into a ticket, chat or shared document. The step is done when the secret store shows the entry, access is limited to the people and automation that deploy Grafana, and the owner has confirmed the value is recorded in your key inventory.
Place the key through your install method's mechanism
The engineer who manages the deployment sets the secret_key value in the Grafana configuration file, or through the environment variable or Helm chart value your install method supports, pulling it from the secret store at deploy time rather than hard-coding it in a template. Confirm the exact setting name for your version in the installation documentation before you change anything. The step is done when the rendered configuration on the host or pod contains the key and the file itself is readable only by the Grafana service account and administrators.
Confirm every HA node uses the identical value
If you run two or more active-active Grafana servers behind a load balancer, the engineer checks that each node receives exactly the same key, because a node with a different key cannot decrypt credentials written by its peers. Compare a fingerprint of the value (for example, a keyed hash computed from the secret store copy) on each node rather than printing the key itself. The step is done when all nodes report the same fingerprint and no node logs a decryption error during startup.
Start Grafana and create a test data source
The engineer starts Grafana on all nodes, signs in as an administrator, and creates a test data source with a dummy credential such as a password or token that is clearly marked as test data. The engineer then runs a query against that data source to confirm Grafana can read the credential it just stored. The step is done when the data source test succeeds on every node and the credential is accepted after a page refresh from a different node.
Inspect the database for plaintext credentials
A DBA or engineer with read access to the Grafana database queries the table that holds data source configuration and searches for the test credential string in plaintext. The value should appear only in an encrypted form. The DBA also confirms that the key itself does not appear in any database table, log file or backup. The step is done when the search returns no plaintext match and the findings are recorded with the query, date and database name in your change record.
Run restart and backup restore tests
The engineer restarts one Grafana node and confirms the test data source still works, then restores a recent database backup into a separate non-production environment configured with the same key and checks that the test credential decrypts. A second restore attempt with a deliberately wrong key should fail, which confirms the key is required. The step is done when the restart, the successful restore and the expected failure with the wrong key are all documented, because a backup is only useful if you can read it with the key you hold.
Record a rollback point before production data
Before any production data source or user is added, the platform owner takes a verified backup of the Grafana database, records the key's location and version in the secret store, and writes down the procedure for restoring the original configuration if the key must be replaced. Confirm the recovery steps with the team that owns the database and secret store. The step is done when the backup has been restored successfully once, the rollback procedure is signed off, and the change record is approved to proceed to production.
Re-encrypting stored secrets after a key change
Changing the key that protects Grafana's stored secrets is a planned operation, not a configuration edit. Data source passwords and tokens in the Grafana database are encrypted with keys derived from the secret_key setting, so changing that value without first re-encrypting the stored secrets leaves existing data sources unable to connect. Whether Grafana offers a supported re-encryption command, what that command does to each secret, and which steps are required depend on the installed version. Treat the documented procedure for that exact version as the only plan you execute, and confirm it in the Grafana docs before you schedule any change.
Before the change, prepare a verified backup of the database and the configuration file, and confirm that you can restore both. Plan a maintenance window long enough to run the re-encryption, check results and restart Grafana, and keep a current list of every data source that stores credentials, with its owner and the test query that proves it works. Write a rollback plan that states how to restore the backup and the previous secret_key. Then restore the backup to a separate test instance, apply the new key there, and confirm that data sources still connect before touching production.
Schedule the change around Grafana's release cadence. The upgrade guidance describes major releases once a year in April or May, minor releases every other month and patch releases at least monthly, and each minor release is supported for a set period. If your installed minor line is close to end of support, or a planned upgrade falls in the same window, combine the work so you do not re-encrypt twice. Ask your vendor or DeployOpen to confirm which release the procedure applies to, whether the re-encryption step changes between minor versions, and what the team must verify after the restart.
KMS options in Grafana Enterprise versus open source
In the open-source edition, the key that protects stored data source credentials is the secret_key value set in the server configuration or supplied through the environment. Grafana uses it to encrypt secrets before they are written to the database, so your team owns the key from creation through retirement. This edition does not provide a KMS integration for holding that key, so custody depends on the controls around your hosts and backups.
- Key source: Set the value in the
[security]section ofgrafana.inior through an environment override, and confirm the override name for your version in the configuration docs. - Operator controls: Key generation, storage, backup, host access, and the timing and procedure of any change.
- Vendor controls: None at runtime. Grafana performs the encryption with the key you supply.
- Key custody questions: Who can read the configuration file or container environment, where database and configuration backups are kept, and whether a restored backup can still decrypt its secrets with the key you hold.
Check that the key is recorded in your secrets manager, that a restore test has succeeded with it, and that your change procedure covers re-encryption before any rotation.
Grafana Enterprise is offered as a non-AGPL commercial option under Grafana Labs licensing. The Enterprise documentation describes KMS integrations for managing the encryption key, but the supported providers, configuration steps and re-encryption procedure must be confirmed against the documentation for your version before you rely on them. License scope, support and upgrade rights come from your agreement with the vendor.
- Commercial terms: Enterprise is licensed separately from the AGPLv3 open-source edition, so get license scope, support and upgrade rights in writing. See the Grafana Labs licensing page.
- Operator controls: Choice of KMS provider, key policies, the IAM role granted to the Grafana service, and the rotation schedule once confirmed.
- Vendor controls: Software behavior of the integration and the support commitments defined in the agreement.
- Key custody questions: Which party holds the root key, who in your organization can disable or delete it, how Grafana behaves if it loses permission to the key, and how a provider outage affects startup.
Ask the vendor for the supported KMS provider list, the re-encryption steps for your version and a test plan that proves a restored instance can start and read its secrets.
In Grafana Cloud, Grafana Labs operates the instance, so your platform team does not manage the database or the server configuration directly. Key management for stored secrets sits inside the managed service, and the split of duties follows the service terms and documentation, so read them before you assume any division of responsibility. Your team still decides what data flows in and who can see it.
- Vendor controls: Hosting, patching, storage encryption and key operations inside the managed platform, as described in the service documentation and terms.
- Operator controls: Which data sources are connected, which credentials are entered, user and role administration, and who can export dashboards and data.
- Cost components: The Grafana pricing page lists a free tier, a Pro tier with a 19 US dollar monthly platform fee plus usage, and an Enterprise tier with a minimum commitment of 25,000 US dollars per year. Confirm current terms, since pricing changes.
- Key custody questions: Whether customer-managed keys are offered, which regions hold data and keys, how rotation is evidenced, and how deleting a stack removes key material.
- Exit path: How you export dashboards, provisioning files and data, since moving off a managed instance may not carry your key custody with it.
Request the vendor's written description of key ownership, rotation and deletion, and attach it to your data classification record.
Protecting the key, backups and admin access
Grafana's encrypted secrets are only as safe as the key that opens them and the places that copy of the key can reach. The controls below cover who can read the key, where backups go, how key changes are recorded, who can see data source settings, and whether restores still work. Treat them as controls to implement and evidence to collect, not as certifications.
Restrict reads of the configuration file
The secret_key setting lives in the Grafana configuration file or is passed as an environment variable into a container. Anyone who can read either can decrypt stored data source passwords and tokens if they also obtain the database. Confirm that the file is owned by the Grafana service account with restrictive permissions, that container secrets come from your secret store rather than image layers or compose files, and that the value does not appear in CI logs or shared runbooks.
Separate backups from the key
A database backup that holds encrypted data source secrets is only useful to an attacker who also has the key. Store database backups and the key in different locations with different access groups. Ask who can restore a backup, whether restore access is logged, and whether an off-site copy of the key exists under the same controls as the key itself. Keep the separation even when a single team runs both.
Log and review key changes
Changing secret_key requires re-encrypting stored secrets, so each change is a planned event. Record who approved the change, when it was applied, which instance was affected and who verified the result. Grafana's audit logging in open-source editions is limited, so use your change tickets, configuration management history and server logs as the evidence trail. Review these records on a fixed schedule.
Limit admin rights over data sources
Organization administrators and server administrators can see data source settings, which may expose connection details and stored credentials in some configurations. Keep the admin role small, separate day-to-day dashboard editing from data source management, and confirm which users can open the data source configuration pages. Review this list after every team change, since admin access tends to accumulate over time.
Test restores with the key in place
A backup that restores into an instance with a different or missing secret_key will leave data source credentials unreadable. Run a restore test on a non-production instance using the same key version that was active when the backup was taken. Check that data sources connect, that alerting notifications still reach their contact points and that the test instance is then wiped. Record the result as evidence.
Apply baseline hardening settings
Key protection sits alongside browser and transport settings that the Grafana hardening guide covers. Review secure and SameSite cookies, the Content Security Policy, Trusted Types, whether the version is hidden from unauthenticated users, authentication on the metrics endpoint and domain verification against DNS rebinding. Each setting should be recorded with its current value, and changes should follow the same change control as key rotation.
Rotating data keys and what a rotation touches
Plan two different operations here: replacing the root secret that protects Grafana's encryption, and rotating the data keys used for stored secrets. In envelope encryption, a root key wraps the data keys, and the data keys encrypt the individual values such as data source passwords and tokens. In a self-hosted Grafana, the root secret is the secret_key setting in the [security] section of grafana.ini. Changing that value without a planned re-encryption step can leave stored credentials unreadable. Before any change, confirm in the Grafana docs for your installed version and edition whether a separate data key rotation exists, and whether it is available in the open-source edition or only in Enterprise.
A rotation touches the credentials stored in the configuration database, which is SQLite, MySQL or PostgreSQL depending on your installation, so the database backups must be planned alongside it. Old backups still hold values encrypted under the previous key, so decide how long they are retained and whether they are re-encrypted or restored only with the matching key. In high availability, every active node shares that database and must run with the same key material, so the change needs an ordered restart plan. Provisioning files that reference secrets, and automation such as Terraform or Git Sync pipelines that supply them, must be updated in the same change. Dashboard definitions generally do not hold encrypted credentials, but confirm this for each data source you use.
Rotation frequency is a policy decision for your security and compliance owners, not a Grafana default, so write down the interval and the event-driven triggers, such as staff changes or suspected exposure. Some organizations instead move secrets into an external secrets manager. OpenBao encrypts values before writing them to storage and supports dynamic secrets and automatic revocation, which changes who owns the key lifecycle. Treat that as a separate design choice with its own high availability, backup and upgrade work, and use it as a comparison point against the in-database approach before you commit.
Limits to confirm in your Grafana version and environment
The encryption design on this page depends on details that change by version, edition and deployment. Confirm each item below with Grafana Labs or your own platform team before you write it into a control narrative or an audit response.
Encryption behavior for your installed version
Confirm how your exact Grafana release encrypts data source passwords and tokens, which key material it uses, and where that key is read from at startup. Ask whether the envelope scheme and key derivation differ between the versions you run now and the versions you plan to move to. Record the answer against the version number in your change records, because a control that was true on one release may not hold on the next.
KMS providers in your edition
Confirm with Grafana Labs which external key management services the Enterprise edition supports, and whether each one is available on self-hosted deployments or only in Grafana Cloud. Ask which cloud KMS and which on-premises key stores are covered, how authentication to the KMS is configured, and what happens to startup if the KMS is unreachable. Do not assume a provider is supported because a similar product is listed elsewhere.
Re-encryption and rotation as operations
Confirm whether changing the secret key and re-encrypting stored secrets is a supported, documented operation for your version, and whether it runs online or needs a maintenance window. Ask whether rotating data keys is supported separately from rotating the root key, and what the procedure is when some nodes in a cluster run a different version. Request the exact steps and the rollback path in writing before you schedule a rotation.
Alerting and Live limits in HA
Confirm how alerting configuration and notification credentials behave in a multi-node setup, including whether contact point secrets are encrypted the same way as data source secrets. Ask Grafana Labs which Grafana Live features are limited in high availability and whether any of them handle secret-bearing data. Test a failover with live data source connections to confirm that secrets remain protected on every node.
Secrets leaking through provisioning and logs
Check whether provisioning files, environment variables and container definitions carry plaintext passwords or tokens that end up in version control, deployment logs, shell history or backups. Ask Grafana Labs whether any startup or debug logging echoes configuration values. Confirm that your backup policy treats the database and the secret key as separate assets, and that restoring one without the other is tested.
License edition against auditor expectations
Confirm the edition and license terms in force before you map controls to an assessment. Some key management features, audit logging and SSO options are tied to Enterprise, so an open-source deployment may not provide the evidence an auditor expects for key handling. Ask your auditor which controls they will test and which evidence they accept, and agree the mapping before design freezes.
Questions buyers ask about Grafana key management before hiring help
How much work is Grafana secrets encryption, and what drives the effort?
Effort depends on how many places Grafana stores credentials and how the instance is built. The main drivers are the number of data sources with saved passwords or tokens, whether Grafana runs as a single server or as a high availability set sharing a MySQL or PostgreSQL database, the edition you run, and whether an existing secrets manager already issues the credentials Grafana uses. Audit requirements add work because you must show who held the key, when it changed and how re-encryption was verified. Ask any partner to split the quote into discovery, key setup, re-encryption testing and runbook handover so you can see which parts grow with your estate.
Can our own team set up Grafana key management without outside help?
Yes, for the core key setup on open-source Grafana, if the team can edit the server configuration, manage database backups and run a planned change window. The core steps are to set the secret_key value outside the database, confirm the instance starts cleanly, and then restore a backup to a separate host using that same key. The restore test is the only reliable proof that the backup can be read later. An engineer who has handled Linux service changes and database migrations can usually do the work, but a second person should review the runbook before the first key change.
How long does a Grafana key management project take?
Duration depends on scope, and no single figure applies to every estate. A single instance with a few data sources and an existing backup routine is a much smaller job than a clustered deployment with several databases, multiple teams and audit evidence to produce. DeployOpen agrees scope, deliverables and timelines in writing before work starts, and a fixed-scope quote follows that written scope. Ask for the timeline to be tied to named milestones, such as the test restore, the first re-encryption and the handover, and ask which change windows the plan assumes.
Does open-source Grafana include a key management service (KMS)?
Confirm this against the current Grafana documentation before you plan around it. Grafana has been published under AGPLv3 since April 20, 2021, and Grafana Enterprise is offered as a separate commercial option. Our understanding is that KMS-backed encryption options are part of Enterprise, but the exact options depend on the version you run. Check the Grafana licensing page for the current edition split, and ask the vendor which key management integrations your version supports. If your policy requires a KMS, request an Enterprise license quote or document an alternative key handling process and its gaps.
What do you need from our team to start a Grafana key project?
We need access in a few specific places before work starts, and your team must make decisions only it can make. Access is required to the Grafana hosts or containers and to the database that holds Grafana's configuration and stored data source credentials. The work also needs the following from your side:
- Current backups and a window to test a restore to a separate host
- Approved change windows for the key change and any re-encryption run
- A named key owner who approves rotation, controls where the key is stored and signs off the runbook
Does DeployOpen issue audit reports for our Grafana key controls?
No. DeployOpen prepares systems, controls and evidence for compliance assessments, including documented key handling, change records and restore test results. Independent auditors and certification bodies issue audit reports, attestations and certifications. The evidence we prepare feeds their assessment, but they make the determination. Ask your auditor early which evidence they expect for key custody, rotation and access, and agree that list before work starts so the evidence is collected as each change is made.
Should we use OpenBao or Vault to protect Grafana's encryption key?
Only if your Grafana version and process support it, and confirm that first. OpenBao and HashiCorp Vault are secrets managers that suit teams already running one, since they handle dynamic credentials and encryption services. HashiCorp announced in August 2023 that future Vault releases would move to the Business Source License 1.1, while OpenBao is an MPL-2.0 community fork. The OpenBao migration guide was tested only against Vault 1.14.1 community edition, so check any Enterprise features separately. Until the integration is proven, keep the Grafana key in a host or container secret path your team already audits, and plan the external manager as a separate, tested step.
How DeployOpen works on this
DeployOpen plans and implements self-hosted Grafana inside your own infrastructure, including how the instance's secret_key, database credentials and data source secrets are protected and rotated. Each engagement starts from a written scope that names the key source, the database, the upgrade path and the evidence your team will keep.
How we scope
- Inventory every data source credential, token and secret that Grafana stores in its database today.
- Confirm the database engine, the current secret_key handling and where the key is kept, in your own environment.
- Agree in writing whether the design uses a key from your existing KMS or secrets manager, or Grafana Enterprise options.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and re-keying checks are available as a retainer after handover.
How we build
- Configure the secret_key source and key storage so the key is not kept beside the database backups.
- Test a full re-encryption run in a non-production copy before any change touches live data sources.
- Verify that stored data source secrets still work after the key change, using the data sources in use.
- Set key rotation steps and record the order of operations for database, configuration and secret updates.
- Check that the Grafana process can read the key source without exposing it in logs or the process list.
How we hand over
- Document the key architecture, the owner of each key and the location of recovery material.
- Provide a rotation and re-encryption runbook with rollback steps and verification checks for each stage.
- Record the evidence an auditor or assessor is likely to ask for, so your team can show the controls work.
- Walk your operations and security staff through the runbook and the restore procedure before sign-off.
- Hand over configuration as code where your deployment supports it, so changes are reviewed and repeatable.
How we support
- Review secret handling again when Grafana releases a new minor or major version that changes configuration.
- Plan the key rotation schedule with your security team and test it against each Grafana upgrade.
- Confirm the restore path for the key and database together at agreed intervals, not only at the start.
- Support is available as a retainer, scoped in writing to the Grafana versions and integrations you run.
- Retesting after an incident or key exposure is scoped separately and agreed in writing before work begins.
