This is documentation for the next version of K6. For the latest stable release, go to the latest version.
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 singleConfigMap
has a character limit of 1048576 bytes. If you need to have a larger test file, you have to use avolumeClaim
or alocalFile
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://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:
spec:
parallelism: 4
script:
localFile: /test/test.js
runner:
image: <custom-image>
Note
If there is any limitation on the usage ofvolumeClaim
in your cluster, you can use thelocalFile
option. We recommend usingvolumeClaim
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.