Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 243 Commits
.github		.github
examples		examples
internal/testutils		internal/testutils
pkg		pkg
.codespellignore		.codespellignore
.codespellrc		.codespellrc
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
catalog-info.yaml		catalog-info.yaml
go.mod		go.mod
go.sum		go.sum
kubernetes.go		kubernetes.go
kubernetes_test.go		kubernetes_test.go

Repository files navigation

xk6-kubernetes

A k6 extension for interacting with Kubernetes clusters while testing.

Build

To build a customk6 binary with this extension, first ensure you have the prerequisites:

Go toolchain
Git

Downloadxk6:
```
go install go.k6.io/xk6/cmd/xk6@latest
```
Build the k6 binary:
```
xk6 build --with github.com/grafana/xk6-kubernetes
```
Thexk6 build command creates a k6 binary that includes the xk6-kubernetes extension in your local folder. This k6 binary can now run a k6 test usingxk6-kubernetes APIs.

Development

To make development a little smoother, use theMakefile in the root folder. The default target will format your code, run tests, and create ak6 binary with your local code rather than from GitHub.

git clone git@github.com:grafana/xk6-kubernetes.gitcd xk6-kubernetesmake

Using thek6 binary withxk6-kubernetes, run the k6 test as usual:

./k6 run k8s-test-script.js

Usage

By default, the API assumes akubeconfig configuration is available at$HOME/.kube.

Alternatively, you can pass in the following options as a javascript Object to the Kubernetes constructor to configure access to the Kubernetes API server:

Option	Value	Description
config_path	/path/to/kubeconfig	Kubeconfig file location. You can also set this to __ENV.KUBECONFIG to use the location pointed by the`KUBECONFIG` environment variable
server	<SERVER_HOST>	Kubernetes API server URL
token		Bearer Token for authenticating to the Kubernetes API server

import{Kubernetes}from'k6/x/kubernetes';exportdefaultfunction(){constk=newKubernetes({config_map:'/path/to/kubeconfig',});}

APIs

Generic API

This API offers methods for creating, retrieving, listing and deleting resources of any of the supported kinds.

Method	Parameters	Description
apply	manifest string	creates a Kubernetes resource given a YAML manifest or updates it if already exists
create	spec object	creates a Kubernetes resource given its specification
delete	kind	removes the named resource
	name
	namespace
get	kind	returns the named resource
	name
	namespace
list	kind	returns a collection of resources of a given kind
	namespace
update	spec object	updates an existing resource

Examples

Creating a pod using a specification

import{Kubernetes}from'k6/x/kubernetes';constpodSpec={apiVersion:"v1",kind:"Pod",metadata:{name:"busybox",namespace:"testns"},spec:{containers:[{name:"busybox",image:"busybox",command:["sh","-c","sleep 30"]}]}}exportdefaultfunction(){constkubernetes=newKubernetes();kubernetes.create(pod)constpods=kubernetes.list("Pod","testns");console.log(`${pods.length} Pods found:`);pods.map(function(pod){console.log(`${pod.metadata.name}`)});}

Creating a job using a YAML manifest

import{Kubernetes}from'k6/x/kubernetes';constmanifest=`apiVersion: batch/v1kind: Jobmetadata:  name: busybox  namespace: testnsspec:  template:    spec:      containers:      - name: busybox        image: busybox        command: ["sleep", "300"]    restartPolicy: Never`exportdefaultfunction(){constkubernetes=newKubernetes();kubernetes.apply(manifest)constjobs=kubernetes.list("Job","testns");console.log(`${jobs.length} Jobs found:`);pods.map(function(job){console.log(`${job.metadata.name}`)});}

Interacting with objects created by CRDs

For objects outside of the core API, use the fully-qualified resource name.

import{Kubernetes}from'k6/x/kubernetes';constmanifest=`apiVersion: networking.k8s.io/v1kind: Ingressmetadata:  name: yaml-ingress  namespace: defaultspec:  ingressClassName: nginx  rules:  - http:      paths:      - path: /my-service-path        pathType: Prefix        backend:          service:            name: my-service            port:              number: 80`exportdefaultfunction(){constkubernetes=newKubernetes();kubernetes.apply(manifest);constingresses=kubernetes.list("Ingress.networking.k8s.io","default")console.log(`${ingresses.length} Ingress found:`);ingresses.map(function(ingress){console.log(`${ingress.metadata.name}`)});}

Helpers

Thexk6-kubernetes extension offers helpers to facilitate common tasks when setting up a tests. All helper functions work in a namespace to facilitate the development of tests segregated by namespace. The helpers are accessed using the following method:

Method	Parameters	Description
helpers	namespace	returns helpers that operate in the given namespace. If none is specified, "default" is used

The methods above return an object that implements the following helper functions:

Method	Parameters	Description
getExternalIP	service	returns the external IP of a service if any is assigned before timeout expires
	timeout in seconds
waitPodRunning	pod name	waits until the pod is in 'Running' state or the timeout expires. Returns a boolean indicating of the pod was ready or not. Throws an error if the pod is Failed.
	timeout in seconds
waitServiceReady	service name	waits until the given service has at least one endpoint ready or the timeout expires
	timeout in seconds

Examples

Creating a pod and wait until it is running

import{Kubernetes}from'k6/x/kubernetes';letpodSpec={apiVersion:"v1",kind:"Pod",metadata:{name:"busybox",namespace:"default"},spec:{containers:[{name:"busybox",image:"busybox",command:["sh","-c","sleep 30"]}]}}exportdefaultfunction(){constkubernetes=newKubernetes();// create podkubernetes.create(pod)// get helpers for test namespaceconsthelpers=kubernetes.helpers()// wait for pod to be runningconsttimeout=10if(!helpers.waitPodRunning(pod.metadata.name,timeout)){console.log(`"pod${pod.metadata.name} not ready after${timeout} seconds`)}}