Authenticate on the CLI
To run cloud tests from the CLI, you need to authenticate your account. Authentication is required both for tests that run on the cloud service and for results that stream to the cloud service. To authenticate accounts, k6 provides an API token, which you can pass on the CLI or through the REST API.
You can generate two types of API tokens for k6 Cloud, depending on how you want to authenticate:
- Personal level API tokens grant access through your account with the Grafana Cloud k6 App.
- Stack level API tokens grant access for actions not tied to a user but to the Grafana Cloud Stack.
To generate API tokens, follow these steps.
Get a personal API token
A personal API token provides API access to your account with k6.
In Grafana Cloud, go to k6 Cloud App > Settings > Personal API token.
On this section, you can copy, see, and regenerate your personal API token.
Note
k6 API tokens don’t have an expiration date. If you wish to rotate your k6 keys, you have to do it manually. It’s recommended that you rotate your k6 keys periodically to ensure appropriate security.
Get a Grafana Stack API token
Note
Only admins can access and manage these tokens.
A Stack API token provides access to all projects within the Grafana Cloud Stack. You can use it to run tests without linking the run to a specific user, e.g. when running tests from a CI platform. To generate a token, follow these steps:
In Grafana Cloud, go to k6 Cloud App > Settings > Grafana Stack API token.
On this section, you can create, see, and regenerate the tokens.
By default, organizations can create a maximum of 5 tokens.
Note that you must specify the project where the test runs will be created when using a non-personal token. Check out how to set the projectID
.
Authenticate with the login
command
To authenticate with an API token in the CLI, enter the following command:
k6 cloud login --token $TOKEN
k6 login
stores your API Token in a local config file to authenticate when running cloud commands. Unless your token changes or you run tests on multiple cloud accounts, you need to run k6 login
only once
Authenticate with an environment variable
You can also authenticate with your k6 Cloud API authentication token via environment variables.
Make sure you have set the K6_CLOUD_TOKEN
as your authentication token, and k6 will pick it up when running.
## run a cloud test
K6_CLOUD_TOKEN=$TOKEN k6 cloud run script.js
## run locally and stream to the cloud
K6_CLOUD_TOKEN=$TOKEN k6 cloud run --local-execution script.js
Authenticate with a config file
You can also directly add your authentication token to a configuration file:
On Linux:
${HOME}/.config/loadimpact/k6/config.json
On Mac
${HOME}/Library/Application Support/loadimpact/k6/config.json
On Windows
C:\Users\<User>\AppData\Roaming\loadimpact\k6\config.json
Or, set the config path with the -c/--config PATH/TO/CONFIG_FILE
CLI flag.
After your token has been added to the config file, it should look something like this (removing any other config options from the file):
{
"collectors": {
"cloud": {
"token": "YOUR_API_AUTH_TOKEN"
}
}
}
Authenticate in Docker
If you’re running k6 in a Docker container, the -c/--config
CLI flag is the recommended approach.
This ensures that the k6 config file where the API authentication information is stored is persisted via a Docker volume to the host machine.
docker run --rm -i -v /path/on-host:/path/in-container/ grafana/k6 \
login cloud -c /path/in-container/config.json