Documentation Grafana k6 Set up Set up distributed k6 Usage Run k6 scripts with TestRun CRD

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:

bash Copy

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

Then specify it in TestRun:

bash Copy

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

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:

yaml Copy

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

Copy

├── 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:

js Copy

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

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

export default function () {
  stressTest();
}

js Copy

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

export default () => {
  const res = http.get('https://test-api.k6.io');
  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:

yaml Copy

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

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:

bash Copy

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:

bash Copy

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

Alternatively, you can create an archive with k6:

bash Copy

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:

bash Copy

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:

yaml Copy

# ...
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:

yaml Copy

# 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:

bash Copy

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:

bash Copy

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

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

yaml Copy

spec:
  cleanup: 'post'

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