Secret source on Grafana Labs

File secret source

Mon, 21 Sep 2026 15:16:28 +0000

File secret source

The file secret source loads secrets from a plain text file.

Each line in the file contains one secret in key=value format:

secret=very secret
someotherkey=another secret

To use the file secret source, specify the file path with the --secret-source flag:

k6 run --secret-source=file=secrets.file script.js

docker run -it --rm \
  -v <SCRIPT_DIR>:/scripts \
  grafana/k6 run --secret-source=file=/scripts/secrets.file /scripts/script.js

In the Docker example, replace <SCRIPT_DIR> with the absolute path to the directory that contains your script and secrets file.

Mock secret source

Mon, 21 Sep 2026 15:16:28 +0000

Mock secret source

The mock secret source provides a quick way to test scripts with secrets.

Note
Don’t use the mock secret source in production. This source is designed for testing purposes only.

To use the mock secret source, provide secrets directly in the command line:

k6 run --secret-source=mock=mysecret=value script.js

docker run -it --rm \
  -v <SCRIPT_DIR>:/scripts \
  grafana/k6 run --secret-source=mock=mysecret=value /scripts/script.js

In the Docker example, replace <SCRIPT_DIR> with the absolute path to the directory that contains your script.

Use multiple mock sources

Configure multiple mock sources and assign them names. You can also set one as the default source.

The following example configures two mock sources: one default source and one named another:

k6 run --secret-source=mock=default,cool="cool secret" --secret-source=mock=name=another,cool="not cool secret" multi-source.test.js

The following script demonstrates how to retrieve secrets from different sources:

import secrets from "k6/secrets";

export default async () => {
  const my_secret = await secrets.get("cool");
  console.log(my_secret == "cool secret");
  const anothersource = await secrets.source("another")
  console.log(await anothersource.get("cool") == "cool secret");
  console.log(await anothersource.get("cool") == "not cool secret");
}

URL secret source

Mon, 21 Sep 2026 15:16:28 +0000

URL secret source

The URL secret source fetches secrets from generic HTTP endpoints.

This source fetches secrets via HTTP requests and supports custom headers, JSON path extraction, rate limiting, and automatic retries.

Basic usage

To use the URL secret source, specify a URL template with the --secret-source flag:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key} script.js

docker run -it --rm \
  -v <SCRIPT_DIR>:/scripts \
  grafana/k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key} /scripts/script.js

k6 replaces the {key} placeholder with the secret identifier when it fetches secrets.

Configuration options

The URL secret source supports three configuration methods:

Inline CLI arguments: Key-value pairs in the --secret-source flag
JSON configuration file: Referenced via config=path/to/file.json
Environment variables: Prefixed with K6_SECRET_SOURCE_URL_

Configuration parameters

Parameter	Type	Default	Description
`urlTemplate`	string	(required)	URL template with `{key}` placeholder
`method`	string	`GET`	HTTP method to use
`headers.*`	string	-	Custom headers. For example, `headers.Authorization=Bearer token`
`responsePath`	string	-	JSON path to extract the secret from the response. If empty, k6 uses the entire response
`timeout`	string	`30s`	Request timeout (e.g., `30s`, `1m`, `500ms`)
`requestsPerMinuteLimit`	int	`300`	Maximum requests per minute
`requestsBurst`	int	`10`	Burst of requests above rate limit
`maxRetries`	int	`3`	Maximum retry attempts for failed requests
`retryBackoff`	string	`1s`	Base backoff duration for retries

Inline configuration

Provide configuration as comma-separated key-value pairs:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key},headers.Authorization=Bearer mytoken,timeout=10s script.js

File-based configuration

Create a JSON configuration file:

{
  "urlTemplate": "https://api.example.com/secrets/{key}",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer mytoken",
    "X-Custom-Header": "value"
  },
  "responsePath": "data.value",
  "timeout": "30s",
  "requestsPerMinuteLimit": 300,
  "requestsBurst": 10,
  "maxRetries": 3,
  "retryBackoff": "1s"
}

Reference the file with the config parameter:

k6 run --secret-source=url=config=secrets-config.json script.js

You can override file settings with inline parameters:

k6 run --secret-source=url=config=secrets-config.json,timeout=5s script.js

Environment variables

Configure using environment variables with the prefix K6_SECRET_SOURCE_URL_:

export K6_SECRET_SOURCE_URL_URL_TEMPLATE="https://api.example.com/secrets/{key}"
export K6_SECRET_SOURCE_URL_HEADER_AUTHORIZATION="Bearer mytoken"
export K6_SECRET_SOURCE_URL_METHOD="GET"
export K6_SECRET_SOURCE_URL_RESPONSE_PATH="data.value"
export K6_SECRET_SOURCE_URL_TIMEOUT="30s"
export K6_SECRET_SOURCE_URL_MAX_RETRIES="3"
export K6_SECRET_SOURCE_URL_RETRY_BACKOFF="1s"
export K6_SECRET_SOURCE_URL_REQUESTS_PER_MINUTE_LIMIT="300"
export K6_SECRET_SOURCE_URL_REQUESTS_BURST="10"

k6 run script.js --secret-source=url

Configuration precedence

When you use multiple configuration methods, k6 applies them in this order:

Default values
Environment variables
Configuration file
Inline CLI arguments

Response handling

Plain text responses

If no responsePath is specified, the entire response body is treated as the secret:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key} script.js

JSON responses

Extract specific values from JSON responses using dot notation:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key},responsePath=data.value script.js

For this JSON response:

{
  "data": {
    "value": "my-secret-value"
  }
}

The secret source extracts "my-secret-value".

Rate limiting

The URL secret source includes built-in rate limiting to prevent overwhelming the secret service:

requestsPerMinuteLimit: Maximum requests per minute (default: 300)
requestsBurst: Allows a burst of requests above the limit (default: 10)

k6 automatically queues requests that exceed the rate limit.

Retry behavior

k6 automatically retries failed requests with exponential backoff:

k6 retries server errors (5xx), rate limiting (429), network errors, and timeouts
k6 doesn’t retry client errors (4xx except 429)
Backoff calculation: wait = (base ^ attempt) + random jitter up to 1 second
Default settings: 3 retries with 1 second base backoff

Examples

Basic API with authentication

Fetch secrets from an API that requires a bearer token:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key},headers.Authorization=Bearer mytoken script.js

JSON API with nested response

Extract a specific value from a nested JSON response:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key},responsePath=secret.data.value,headers.X-API-Key=apikey123 script.js

Custom timeout and retry settings

Configure shorter timeouts and more aggressive retries:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key},timeout=5s,maxRetries=5,retryBackoff=2s script.js

POST request with custom headers

Use POST method with multiple custom headers:

k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key},method=POST,headers.Content-Type=application/json,headers.X-Custom-Header=value script.js

Multiple URL sources

Configure multiple URL secret sources with different names:

k6 run \
  --secret-source=url=default,urlTemplate=https://api1.example.com/secrets/{key},headers.Authorization=Bearer token1 \
  --secret-source=url=name=backup,urlTemplate=https://api2.example.com/secrets/{key},headers.Authorization=Bearer token2 \
  script.js

Access different sources in your script:

import secrets from 'k6/secrets';

export default async () => {
  // Default source
  const secret1 = await secrets.get('my-key');

  // Named source
  const backupSource = await secrets.source('backup');
  const secret2 = await backupSource.get('my-key');
};

Cloud secret source

Mon, 21 Sep 2026 15:16:28 +0000

Cloud secret source

When you run tests in Grafana Cloud using k6 cloud run, secrets management is available automatically. The cloud secret source brings that same access to local execution runs with k6 cloud run --local-execution, so you can use the same secrets without managing credentials locally.

Note
The cloud secret source only works with k6 cloud run --local-execution. Using it with k6 run returns an error.

Before you begin

Authenticate with Grafana Cloud k6 using k6 cloud login.
Configure the secrets you want to use in Grafana Cloud k6.

Use the cloud secret source

Starting in k6 v2.0.0, the cloud secret source is enabled automatically when you run k6 cloud run --local-execution. You don’t need to pass any flag, and secrets.get() works out of the box:

k6 cloud run --local-execution script.js

k6 automatically configures the credentials needed to fetch secrets from Grafana Cloud. No tokens, endpoints, or passwords are required on the command line.

k6 automatically redacts all secrets from logs.

Opt out with `--no-cloud-secrets`

If you don’t want the cloud secret source enabled, pass --no-cloud-secrets:

k6 cloud run --local-execution --no-cloud-secrets script.js

With this flag, calls to secrets.get() for the cloud source will fail unless you explicitly configure another source.

Secret source on Grafana Labs

File secret source

File secret source

Mock secret source

Mock secret source

Use multiple mock sources

URL secret source

URL secret source

Basic usage

Configuration options

Configuration parameters

Inline configuration

File-based configuration

Environment variables

Configuration precedence

Response handling

Plain text responses

JSON responses

Rate limiting

Retry behavior

Examples

Basic API with authentication

JSON API with nested response

Custom timeout and retry settings

POST request with custom headers

Multiple URL sources

Cloud secret source

Cloud secret source

Before you begin

Use the cloud secret source

Opt out with --no-cloud-secrets

Opt out with `--no-cloud-secrets`