Documentation Grafana Cloud Testing and synthetics Performance testing Author and run tests 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. k6 tests reference secrets in a way that prevents them from being exposed in the UI, scripts, and generated logs.

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 tests in Grafana Cloud, and also tests executed by running k6 cloud locally.
• 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 k6 tests by referencing the secret name, 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

• You need to have the proper clearance to manage secrets, refer to the Role-based access control section for more details.
• 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 Testing & synthetics > Performance > Settings.
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. Can contain letters, numbers, hyphens, and underscores.
   2. Description: An optional description explaining the secret’s purpose.
   3. Value: The secure value to be encrypted. This field is masked for security.
   4. Labels: Extra metadata to help with organizing secrets.
5. Click Save to create the secret.

Note that the secret is available for use only in Grafana Cloud k6 tests. You can’t access it with other Grafana Cloud applications.

Edit a secret

To edit a secret:

1. Navigate to Testing & synthetics > Performance > Settings.
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 Testing & synthetics > Performance > Settings.
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 test

To use secrets in a test:

1. Navigate to Testing & synthetics > Performance > Projects.
2. Create a new project or select a previously created one.
3. Click “Create new test”.
4. Click “Start scripting”.
5. 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');
6. 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.

Note that the secrets module is available in k6 version 1.5.0 or newer. If you’re overriding the k6 version, ensure it’s that version or newer.

Run k6 scripts locally with secrets

There are different ways to reference secrets in a k6 script running locally, as there are several secret sources built into k6.

In some of these secret sources, the user must provide the secret values. That is the case for the mock source (secrets are defined as comma-separated key-value pairs after the --secret-source=mock command line argument), the file source (secrets are read from a file), or the url source (secrets are fetched from any HTTP service). Refer to the Secret source documentation for more details on those.

If the secrets are stored in Grafana Cloud, they can be retrieved when running k6 from the command line by using the k6 cloud command. Note that the k6 version must be equal to or greater than 1.5.0.

Secrets can’t be currently retrieved when running a test by using k6 cloud --local-execution.

Role-based access control

• Only users with the Admin or Editor role, or the Performance Testing (k6): Editor permission, can use secrets when editing tests. Refer to Manage projects and users for more details.

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

Admins and Editors can create, edit, and delete secrets by default. On the other hand users with the Grafana Viewer role can be granted access to create, edit, and delete secrets using specific roles.

You can use those 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 Administration > Users and access > Users.
• Click in the Role column for the desired user, and scroll to Plugin Roles > Performance Testing (k6).
• Assign the desired roles.