Documentation Grafana Cloud Observe and act Test and validate Synthetic Monitoring Create checks Create and manage secrets

Create and manage secrets

Secrets management provides a centralized location to securely store and manage values such as API keys, passwords, tokens, and credentials. Synthetic Monitoring tests reference secrets in a way that prevents them from being exposed in the UI, scripts, and logs generated by Synthetic Monitoring.

With secrets management, you can:

• Create secrets and attach metadata to secrets, such as description and labels.
• Reference secrets by name in k6 scripted and k6 browser synthetics.
• Use secrets for supported authentication and TLS fields in HTTP checks.
• Reset and revoke secret values.

Secrets are encrypted at rest using envelope encryption. Grafana Cloud stores the secrets’ metadata in one location while simultaneously encrypting and storing secret values in a different location. Secret values can only be decrypted by Synthetic Monitoring by using references to the metadata, not the encrypted value itself. This ensures that secrets are never stored permanently and are only available in memory during active use.

Before you begin

• Users with the Grafana Admin role can create, edit, and delete secrets by default.
• Users with the Grafana Editor and Viewer roles can be granted access to create, edit, and delete secrets using a fixed role. Refer to the Role-based access control section for more details.
• Only users with the Admin or Editor role, or the Checks writer permission, can use secrets when editing tests. Refer to Manage users and teams for Synthetic Monitoring for more details.
• Secrets are supported in k6 scripted, k6 browser, and HTTP checks.
• In HTTP checks, you can use secrets for a basic authentication password, a bearer token, a CA certificate, a client certificate, or a client key. You can’t use a secret for a basic authentication username, custom request headers, or proxy connect headers.
• Only text-based secrets, such as passwords and certificates, are supported. Secrets have a limit of 24kB.
• Secret names must be 253 characters or less.
• Secret descriptions must be 253 characters or less.
• Secrets can have a maximum of 10 labels.
• Label keys must be 63 characters or less.

Create a secret

To create a new secret:

1. Navigate to Home > Testing & synthetics > Synthetics > Config.
2. Click the Secrets tab.
3. Click Create secret.
4. In the Create secret dialog box, fill in the following fields:
   1. Name: A unique name for your secret. Use a descriptive name, such as api-key-production. Names can contain lowercase letters, numbers, hyphens, and periods.
   2. Description: An optional description explaining the secret’s purpose.
   3. Value: The secure value to be encrypted. This field is masked for security.
5. Click Save to create the secret.

Edit a secret

To edit a secret:

1. Navigate to Home > Testing & synthetics > Synthetics > Config.
2. Click the Secrets tab.
3. Find the name of the secret you want to edit and click the Edit button next to it.
4. Update the fields you want to change. To update the Value field, click Reset first, and then update the secret’s value.
5. Click Save.

Delete a secret

To delete a secret:

1. Navigate to Home > Testing & synthetics > Synthetics > Config
2. Click the Secrets tab.
3. Find the name of the secret you want to delete and click the trash icon next to it.
4. In the confirmation dialog box, type “Delete”.
5. Click Delete.

Use secrets in a check

Checks store a reference to a secret. The probe retrieves the current secret value when it runs the check. If you reset the secret’s value, subsequent check runs use the new value without requiring you to edit the check.

Use a secret in an HTTP check

Before you begin, create the secret that you want the check to use.

To use a secret in an HTTP check:

1. Navigate to Home > Testing & synthetics > Synthetics > Checks.
2. Create a new API Endpoint check, or edit an existing HTTP check.
3. In the Request section, click Request options.
4. Configure one of the supported fields:
   • For basic authentication, select Authentication > Basic Auth, and then select Secret for Password.
   • For bearer authentication, select Authentication > Bearer Token, and then select Secret for Token.
   • For a TLS certificate or key, select TLS, locate CA certificate, Client certificate, or Client key, and then select Secret.
5. Select the secret by name.
6. In the Execution section, select the probes that run the check.
7. Click Save, or click Test to run the check first.

Use a secret in a k6 check

To use secrets in a test:

1. Navigate to Home > Testing & synthetics > Synthetics > Checks.
2. Click Create new check or Create your first check.
3. Select the Scripted or Browser check type.
4. In your script:
   1. Import the k6/secrets module: import secrets from 'k6/secrets';
   2. Retrieve the secret value by using its name: const secret_value = await secrets.get('test-secret-name');
5. Use the secret value variable in your script.

Here is an example of a minimal k6 scripted test that fetches a secret value and tries to log it:

js Copy

import secrets from 'k6/secrets';

export default async function main() {
  const secret_value = await secrets.get('test-secret-name');

  // Try logging the secret -- the value is redacted
  console.log(`try to log the secret value: ${secret_value}`);
}

Refer to the k6/secrets documentation for more details on the secrets module.

Run k6 scripts locally with secrets

To reference secrets in a k6 script running locally, use the mock and file secret sources built into k6.

The mock source defines secrets as comma-separated key-value pairs after the --secret-source=mock command line argument. Here is an example passing the username ‘default’ and password ‘12345678’ to the script mytest.js:

sh Copy

k6 run --secret-source=mock=username=default,password=12345678 mytest.js

In mytest.js the secrets are retrieved by name:

js Copy

import secrets from 'k6/secrets';

export default async function main() {
  const username = await secrets.get('username'); //fetches the value 'default'
  const password = await secrets.get('password'); //fetches the value '12345678'
  //...
}

The file source reads secrets from a file. This can be a better option when using many secrets or large secrets that are difficult to define on the command line. Define secrets as key=value pairs in a text file. Here is an example file secrets.txt defining the same secrets:

txt Copy

username=default
password=12345678

When running the script pass the --secret-source=file command line argument, followed by the filename. Here is an example passing secrets.txt to the script mytest.js:

sh Copy

k6 run --secret-source=file=secrets.txt mytest.js

Refer to the k6/secrets documentation for more details on secret sources.

Secret redaction

Secret values are masked in the Synthetic Monitoring output with the ***SECRET_REDACTED*** placeholder.

For example, the following script snippet:

js Copy

const result = http.post('https://my-endpoint.test.app', '', { headers: { Authorization: `Bearer ${secret_value}` } });

Produces a header in the form of:

http Copy

Authorization: Bearer xm_MCp5aalOF2BGlafChR8Gu5hv

But that same line appears in the logs as:

http Copy

Authorization: Bearer ***SECRET_REDACTED***

Role-based access control

The ability to create, edit, and delete secrets is defined by the Grafana role assigned to a user:

• Admins can create, edit, and delete secrets by default.
• Only users with the Admin or Editor role, or the Checks writer permission, can use secrets when editing tests.

You can use Role-based access control to give users, whether they’re Admins, Editors, or Viewers, granular access to secrets. The following roles are available:

To assign a role to a user:

• Navigate to Home > Administration > Users and access > Users.
• Assign a fixed role from Fixed roles > Secret manager.

When assigning secret manager roles to users, ensure these users have been granted appropriate access to Synthetic Monitoring. For example, a user with the Grafana Viewer role and the Secure Values Creator role has the ability to create secrets, but they also need the Checks writer role to gain access to the Synthetic checks interface containing the secrets configuration.

Refer to Synthetic Monitoring RBAC roles for more details about the available roles.