Usage on Grafana Labs

Run k6 scripts with TestRun CRD

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

Run k6 scripts with TestRun CRD

This guide covers how you can configure your k6 scripts to run using the k6 Operator.

Defining test scripts

There are several ways to configure scripts in the TestRun CRD. The operator uses configMap, volumeClaim and localFile to serve test scripts to the jobs.

ConfigMap

The main way to configure a script is to create a ConfigMap with the script contents:

kubectl create configmap my-test --from-file /path/to/my/test.js

Then specify it in TestRun:

  script:
    configMap:
      name: my-test
      file: test.js

Note
A single ConfigMap has a character limit of 1048576 bytes. If you need to have a larger test file, you have to use a volumeClaim or a localFile instead.

VolumeClaim

If you have a PVC with the name stress-test-volumeClaim containing your script and any other supporting files, you can pass it to the test like this:

spec:
  script:
    volumeClaim:
      name: 'stress-test-volumeClaim'
      # test.js should exist inside /test/ folder.
      # All the js files and directories test.js is importing
      # should be inside the same directory as well.
      file: 'test.js'

The pods will expect to find the script files in the /test/ folder. If volumeClaim fails, that’s the first place to check. The latest initializer pod doesn’t generate any logs and when it can’t find the file, it exits with an error. Refer to this GitHub issue for potential improvements.

Sample directory structure

├── test
│   ├── requests
│   │   ├── stress-test.js
│   ├── test.js

In the preceding example, test.js imports a function from stress-test.js and these files would look like this:

// test.js
import stressTest from './requests/stress-test.js';

export const options = {
  vus: 50,
  duration: '10s',
};

export default function () {
  stressTest();
}

// stress-test.js
import { sleep, check } from 'k6';
import http from 'k6/http';

export default () => {
  const res = http.get('https://quickpizza.grafana.com');
  check(res, {
    'status is 200': () => res.status === 200,
  });
  sleep(1);
};

LocalFile

If the script is present in the filesystem of a custom runner image, it can be accessed with the localFile option:

spec:
  parallelism: 4
  script:
    localFile: /test/test.js
  runner:
    image: <custom-image>

Note
If there is any limitation on the usage of volumeClaim in your cluster, you can use the localFile option. We recommend using volumeClaim if possible.

Multi-file tests

In case your k6 script is split between multiple JavaScript files, you can create a ConfigMap with several data entries like this:

kubectl create configmap scenarios-test --from-file test.js --from-file utils.js

If there are too many files to specify manually, using kubectl with a folder might be an option as well:

kubectl create configmap scenarios-test --from-file=./test

Alternatively, you can create an archive with k6:

k6 archive test.js [args]

The k6 archive command creates an archive.tar in your current folder. You can then use that file in the configmap, similarly to a JavaScript script:

kubectl create configmap scenarios-test --from-file=archive.tar

If you use an archive, you must edit your YAML file for the TestRun deployment so that the file option is set to the correct entrypoint for the k6 run command:

# ...
spec:
  script:
    configMap:
      name: 'crocodile-stress-test'
      file: 'archive.tar' # <-- change here

Run tests

Tests are executed by applying the custom resource TestRun to a cluster where the k6 Operator is running. Additional optional properties of the TestRun CRD allow you to control some key aspects of a distributed execution. For example:

# k6-resource.yml

apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: k6-sample
spec:
  parallelism: 4
  script:
    configMap:
      name: k6-test
      file: test.js
  separate: false
  runner:
    image: <custom-image>
    metadata:
      labels:
        cool-label: foo
      annotations:
        cool-annotation: bar
    securityContext:
      runAsUser: 1000
      runAsGroup: 1000
      runAsNonRoot: true
    resources:
      limits:
        cpu: 200m
        memory: 1000Mi
      requests:
        cpu: 100m
        memory: 500Mi
  starter:
    image: <custom-image>
    metadata:
      labels:
        cool-label: foo
      annotations:
        cool-annotation: bar
    securityContext:
      runAsUser: 2000
      runAsGroup: 2000
      runAsNonRoot: true

A TestRun CR is created with this command:

kubectl apply -f /path/to/your/k6-resource.yml

Clean up resources

After completing a test run, you need to clean up the test jobs that were created:

kubectl delete -f /path/to/your/k6-resource.yml

Alternatively, you can configure the automatic deletion of all resources with the cleanup option:

spec:
  cleanup: 'post'

With the cleanup option set, k6 Operator removes the TestRun CRD and all created resources once the test run ends.

Use k6 Operator with k6 extensions

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

Use k6 Operator with k6 extensions

By default, the k6 Operator uses ghcr.io/grafana/k6-operator:latest-runner as the container image for the test jobs.

If you want to use k6 extensions built with xk6, you’ll need to create your own image and override the image property on the TestRun Kubernetes resource.

For example, this is a Dockerfile that builds a k6 binary with the xk6-output-influxdb extension:

# Build the k6 binary with the extension
FROM golang:1.25.1 as builder

RUN go install go.k6.io/xk6/cmd/xk6@latest

# For our example, we'll add support for output of test metrics to InfluxDB v2.
# Feel free to add other extensions using the '--with ...'.
RUN xk6 build \
    --with github.com/grafana/xk6-output-influxdb@latest \
    --output /k6

# Use the operator's base image and override the k6 binary
FROM grafana/k6:latest
COPY --from=builder /k6 /usr/bin/k6

You can build the image based on this Dockerfile by executing:

docker build -t k6-extended:local .

After the build completes, you can push the resulting k6-extended:local image to an image repository accessible to your Kubernetes cluster.

You can then use that image as follows:

# k6-resource-with-extensions.yml

apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: k6-sample-with-extensions
spec:
  parallelism: 4
  script:
    configMap:
      name: my-stress-test
      file: test.js
  runner:
    image: k6-extended:local
    env:
      - name: K6_OUT
        value: xk6-influxdb=http://influxdb.somewhere:8086/demo

Note that this examples overrides the default image with k6-extended:latest, and it includes environment variables that are required by the xk6-output-influxdb extension.

Troubleshooting

If a TestRun with a custom image doesn’t start the test and the k6 Operator logs an error about the initializer, run the following command:

docker run --entrypoint sh k6-extended:local -c "ls -l && k6 version"

This command should execute without an error. If there's an error, resolve it by making sure that the `Dockerfile` is correctly configured. Use the sample above as a reference.

Use the k6 Operator with Grafana Cloud k6

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

Use the k6 Operator with Grafana Cloud k6

Grafana Cloud k6 is the Grafana Cloud offering of k6, which gives you access to all of k6 capabilities, while Grafana handles the infrastructure, storage, and metrics aggregation and insights from your tests.

When using the k6 Operator, you can still leverage Grafana Cloud k6 to get access to the metric storage and analysis that the platform offers.

There are two ways to use the k6 Operator with Grafana Cloud k6: Private Load Zones and Cloud output.

Before you begin

To use the k6 Operator with Grafana Cloud k6, you’ll need:

A Grafana Cloud account.

Private Load Zones

Private Load Zones (PLZ) are load zones that you can host inside your network by using the k6 Operator. You can start a cloud test in a PLZ by referencing it by name from your script, and the test will run in the nodes of your Kubernetes cluster.

Refer to Set up private load zones for more details.

Cloud output

With k6, you can send the output from a test run to Grafana Cloud k6 with the k6 run --out cloud script.js command. This feature is also available in the k6 Operator if you have a Grafana Cloud account.

Note
The cloud output option only supports a parallelism value of 20 or less.

To use this option in k6 Operator, set the argument in YAML:

# ...
script:
  configMap:
    name: '<configmap>'
arguments: --out cloud
# ...

Then, if you installed operator with bundle or Helm, create a secret with the following command:

kubectl -n k6-operator-system create secret generic my-cloud-token \
    --from-literal=token=<COPY YOUR TOKEN HERE> && kubectl -n k6-operator-system label secret my-cloud-token "k6cloud=token"

Alternatively, if you installed operator with a Makefile, you can uncomment the cloud output section in config/default/kustomization.yaml and copy your token from Grafana Cloud k6 there:

# Uncomment this section if you need cloud output and copy-paste your token
secretGenerator:
  - name: cloud-token
    literals:
      - token=<copy-paste-token-string-here>
    options:
      annotations:
        kubernetes.io/service-account.name: k6-operator-controller
      labels:
        k6cloud: token

After updating the file, run make deploy.

After these steps, you can run k6 with the cloud output and default values of projectID and name.

Refer to Cloud options for details on how to change the projectID and name options.

Configure the TestRun CRD

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

Configure the TestRun CRD

The only options that are required as part of the TestRun CRD spec are script and parallelism. But there are many other options that can be set in TestRun CRD. Refer to the crd-generated.md file in the k6-operator GitHub repository for a complete list of all available fields.

Let’s look at some of the most common options in greater detail.

Parallelism

parallelism defines how many instances of k6 runners you want to create. Each instance is assigned an equal execution segment. For instance, if your test script is configured to run 200 VUs and parallelism is set to 4, the k6 Operator creates four k6 jobs, each running 50 VUs to achieve the desired VU count.

Separate

separate: true indicates that the jobs created need to be distributed across different nodes. This is useful if you’re running a test with a really high VU count and want to make sure the resources of each node won’t become a bottleneck.

Service account

If you want to use a custom Service Account you’ll need to pass it into both the starter and the runner object:

apiVersion: k6.io/v1alpha1
kind: TestRun
metadata:
  name: <test-name>
spec:
  script:
    configMap:
      name: '<configmap>'
  runner:
    serviceAccountName: <service-account>
  starter:
    serviceAccountName: <service-account>

Runner

Defines options for the test runner pods. The non-exhaustive list includes:

Passing resource limits and requests.
Passing in labels and annotations.
Passing in affinity and anti-affinity.
Passing in a custom image.

Starter

Defines options for the starter pod. The non-exhaustive list includes:

Passing in a custom image.
Passing in labels and annotations.

Initializer

By default, the initializer Job is defined with the same options as the runner Jobs, but its options can be overwritten by setting .spec.initializer.

Schedule k6 tests

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

Schedule k6 tests

While the k6 Operator doesn’t support scheduling k6 tests directly, you can schedule tests with the CronJob object from Kubernetes directly. The CronJob would run on a schedule and execute the creation and deletion of the TestRun object.

Running these tests requires a little more setup than a standalone test run.

Create a `ConfigMap` with k6 scripts

Refer to Run k6 scripts with TestRun CRD for details on how to create a ConfigMap with k6 scripts.

Create a ConfigMap of the YAML file for the `TestRun` job

When using the make deploy installation method, add a configMapGenerator to the kustomization.yaml:

configMapGenerator:
  - name: <test-name>-config
    files:
      - <test-name>.yaml

Create a `ServiceAccount` for the `CronJob`

For the CronJob to be able to create and delete TestRun objects, create a service account:

---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: k6-<namespace>
rules:
  - apiGroups:
      - k6.io
    resources:
      - testruns
    verbs:
      - create
      - delete
      - get
      - list
      - patch
      - update
      - watch
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: k6-<namespace>
roleRef:
  kind: Role
  name: k6-<namespace>
  apiGroup: rbac.authorization.k8s.io
subjects:
  - kind: ServiceAccount
    name: k6-<namespace>
    namespace: <namespace>
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: k6-<namespace>

Create a `CronJob`

This is an example of how to define a CronJob in a YAML file:

# snapshotter.yml
apiVersion: batch/v1beta1
kind: CronJob
metadata:
  name: <test-name>-cron
spec:
  schedule: '<cron-schedule>'
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccount: k6
          containers:
            - name: kubectl
              image: bitnami/kubectl
              volumeMounts:
                - name: k6-yaml
                  mountPath: /tmp/
              command:
                - /bin/bash
              args:
                - -c
                - 'kubectl delete -f /tmp/<test-name>.yaml; kubectl apply -f /tmp/<test-name>.yaml'
          restartPolicy: OnFailure
          volumes:
            - name: k6-yaml
              configMap:
                name: <test-name>-config

Use the k6 Operator with Istio

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

Use the k6 Operator with Istio

To use the k6 Operator against a cluster with Istio support, you may need to perform some additional configuration. Istio has two modes of execution: sidecar mode and ambient mode.

Sidecar mode

If you use Istio in sidecar mode, first, check the versions of your cluster and Istio. For the k6 Operator to work without issues, Istio’s version must be 1.19 or higher, and the Kubernetes version must be 1.28 or higher.

Additionally, Kubernetes cluster must have native sidecars enabled, which is the default behaviour since version 1.29 but must be enabled with a feature gate in version 1.28. Here’s an example of the kind cluster with this configuration:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
featureGates:
  SidecarContainers: true

If the above requirements are not fulfilled, k6 Operator will not be able to work with Istio because of this issue: the non-native sidecar istio-proxy doesn’t exit and all Kubernetes Jobs end up stuck, including the ones started by the k6 Operator. Because of this, k6 Jobs enter a NotReady state, and the k6 Operator doesn’t know how to handle it in a general case.

To solve this, upgrade versions of your cluster and Istio as described above and switch to using Istio with native sidecars. As described in the blog, you need to enable the ENABLE_NATIVE_SIDECARS flag in Istio as well.

Mark k6 pods for Istio injection

Istio in sidecar mode lets you configure injection on Pods and Namespaces.

Since the k6 Operator is not aware of the Istio setup on your cluster, it will, by default, create Pods without Istio labels. If you create a TestRun, you can set the Istio labels via .spec.runner.metadata.labels. If you create a PrivateLoadZone, you can set the labels on the Namespace where the PrivateLoadZone CR is created.

Ambient mode

If you use Istio in ambient mode, the k6 Operator should work out of the box, as Istio in ambient mode doesn’t modify Kubernetes workloads.

Mark k6 pods for Istio injection

Istio in ambient mode lets you configure injection on Pods, Services, and Namespaces.

Similarly to injection in sidecar mode, you can use Pod-level configuration with a TestRun and Namespace-level configuration with a PrivateLoadZone.

Usage on Grafana Labs

Run k6 scripts with TestRun CRD

Run k6 scripts with TestRun CRD

Defining test scripts

ConfigMap

VolumeClaim

Sample directory structure

LocalFile

Multi-file tests

Run tests

Clean up resources

Use k6 Operator with k6 extensions

Use k6 Operator with k6 extensions

Troubleshooting

Use the k6 Operator with Grafana Cloud k6

Use the k6 Operator with Grafana Cloud k6

Before you begin

Private Load Zones

Cloud output

Configure the TestRun CRD

Configure the TestRun CRD

Parallelism

Separate

Service account

Runner

Starter

Initializer

Schedule k6 tests

Schedule k6 tests

Create a ConfigMap with k6 scripts

Create a ConfigMap of the YAML file for the TestRun job

Create a ServiceAccount for the CronJob

Create a CronJob

Use the k6 Operator with Istio

Use the k6 Operator with Istio

Sidecar mode

Mark k6 pods for Istio injection

Ambient mode

Mark k6 pods for Istio injection

Create a `ConfigMap` with k6 scripts

Create a ConfigMap of the YAML file for the `TestRun` job

Create a `ServiceAccount` for the `CronJob`

Create a `CronJob`