vault_plugin_secrets_grafana

Vault Plugin: Grafana Secrets Backend

This is a HashiCorp Vault plugin that generates tokens for Grafana Cloud and standalone Grafana instances.

Download

Binary releases are available at https://github.com/Boostport/vault-plugin-secrets-grafana/releases.

Verify Binaries

The checksum for the binaries are signed with cosign. To verify the binaries, download the following files (where ${VERSION} is the version of the release):

• vault-plugin-secrets-grafana_${VERSION}_checksums.txt
• vault-plugin-secrets-grafana_${VERSION}_checksums.txt.pem
• vault-plugin-secrets-grafana_${VERSION}_checksums.txt.sig

Then download the release binaries you need. Here, we just download the linux amd64 binary:

• vault-plugin-secrets-grafana_${VERSION}_linux_amd64

Then run the following commands to verify the checksums and signature:

# Verify checksum signature
$ cosign verify-blob --signature vault-plugin-secrets-grafana_${VERSION}_checksums.txt.sig --certificate vault-plugin-secrets-grafana_${VERSION}_checksums.txt.pem vault-plugin-secrets-grafana_${VERSION}_checksums.txt --certificate-identity "https://github.com/Boostport/vault-plugin-secrets-grafana/.github/workflows/release.yml@refs/tags/v${VERSION}" --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

# Verify checksum with binaries
$ sha256sum -c vault-plugin-secrets-grafana_${VERSION}_checksums.txt

Getting Started

Grafana Cloud

1. Create an Access Policy in Grafana Cloud with the following scopes: accesspolicies:read, accesspolicies:write, accesspolicies:delete, stacks:read and stack-service-accounts:write.
2. Generate a token for the Access Policy.
3. Configure the Grafana secrets backend:

vault write grafana/config type=cloud token=<token>

1. Create an Access Policy role:

vault write grafana/roles/my-access-policy-role type=cloud_access_policy region=us scopes="accesspolicies:read, accesspolicies:write" realms='[{"type": "org", "identifier": "<org_identifier>", "labelPolicies": []}]'

1. Generate a token for the Access Policy role:

vault read grafana/creds/my-access-policy-role

1. Create a Service Account role:

vault write grafana/roles/my-service-account-role type=grafana_service_account stack=mycompany role=Editor

1. Generate a token for the Service Account role:

vault read grafana/creds/my-service-account-role

Grafana Instance

1. Create a Service Account in your Grafana instance with the Admin basic role, or the following fixed roles: Roles:Role writer, Service accounts:Service account writer.
2. Generate a token for the Service Account.
3. Configure the Grafana secrets backend:

vault write grafana/config type=grafana token=<token> url=<instance_url>

1. Create a Service Account role:

vault write grafana/roles/my-service-account-role role=Editor

1. Generate a token for the Service Account role:

vault read grafana/creds/my-service-account-role

Backend Configuration

Grafana Cloud

Configuration Parameters

Required Scopes for Access Policy:

• accesspolicies:read
• accesspolicies:write
• accesspolicies:delete
• stacks:read
• stack-service-accounts:write

Grafana Instance

Configuration Parameters

Required Roles for Service Account:

• If using basic roles: Admin
• If using fixed roles:
  • Roles:Role writer
  • Service accounts:Service account writer

Role Configuration

Grafana Cloud

For Grafana Cloud, roles can be created to generate either Access Policy tokens or Service Account tokens.

Access Policy Roles

Service Account Roles

Grafana Instance

For Grafana instances, roles can only generate Service Account tokens.

Troubleshooting

Why do I get a 403 error when trying to generate a server account token for Grafana Cloud?

Grafana instances hosted on Grafana Cloud become dormant if they have not been used for a while. This results in service account creation failing when the instance is dormant:

$ vault read grafana/creds/service-account-role
Error reading grafana/creds/service-account-role: Error making API request.

URL: GET http://127.0.0.1:8200/v1/grafana/creds/service-account-role
Code: 500. Errors:

* 1 error occurred:
  * error creating service account: error creating service account from cloud token: error response from server (403): {"code":"Forbidden","traceID":"4dXXXX","message":"operation not allowed"}

To resolve the issue, wake up the Grafana instance by logging into the Grafana Cloud control panel in the browser and launching the Grafana instance.

Developing

To run unit tests, run go test -v ./... from the root of the repository.

To run unit tests and acceptance tests, set the following environment variables and run go test -v ./... from the root of the repository:

Notes:

• Running acceptance tests will create and delete Access Policies and Service Accounts in your Grafana Cloud account.
• To test the backend in Grafana instance mode, we create a test service account in the Grafana Cloud stack and use that to simulate a standalone Grafana instance.