k6build builds custom k6 binaries with extensions.
k6build defines an API for building custom k6 binaries that satisfies a given list of dependencies with their constrains.
The Build operation returns the metadata of the custom binary, including an URL for downloading it,
but does not return the binary itself.
The request for building a binary specifies the target platform (required) and the dependencies, including k6.
The Resolve operation returns the versions that satisfy the given depedency constrains or
an error if they cannot be satisfied.
The dependencies specify the import path (as used in the k6 script) and the semantic version constrains.
Dependencies are mapped by a catalog to the corresponding go module that implements it. The catalog also defines the available versions.
If a dependency doesn't specify a constrains, the latest version (according to the catalog) is used.
See k6catalog for more details on defining a catalog.
The default catalog is defined at https://registry.k6.io/catalog.json
The build server exposes the build API as a REST API.
The client package implements a client for the build REST API.
The k6build's builder collects metrics about the build process in a prometheus compatible format:
- Number of build requests
- Number of build requests satisfied from the object store
- Number of build requests that could not be satisfied (e.g dependency not supported)
- Number of builds
- Number of failed build processes
- Build time histogram
The k6build server exposes these metrics in the /metrics path.
The following sections describe different usage scenarios.
examples/kubernetes describes how to run k6build in a kubernetes cluster and execute k6 tests in a pod using k6exec.
TODO: use k6-operator for running the tests using a custom image.
Build custom k6 binaries with extensions
- k6build local - build custom k6 binary locally
- k6build remote - build a custom k6 using a remote build server
- k6build server - k6 build service
- k6build store - k6build object store server
- k6build version - k6build version
build custom k6 binary locally
k6build local builder creates a custom k6 binary artifacts that satisfies certain dependencies. Requires the golang toolchain and git.
k6build local [flags]
# build k6 v0.51.0 with latest version of k6/x/kubernetes
k6build local -k v0.51.0 -d k6/x/kubernetes
platform: linux/amd64
k6: v0.51.0
k6/x/kubernetes: v0.9.0
checksum: 7f06720503c80153816b4ef9f58571c2fce620e0447fba1bb092188ff87e322d
# build k6 v0.51.0 with k6/x/kubernetes v0.8.0 and k6/x/output-kafka v0.7.0
k6build local -k v0.51.0 \
-d k6/x/kubernetes:v0.8.0 \
-d k6/x/output-kafka:v0.7.0
platform: linux/amd64
k6: v0.51.0
k6/x/kubernetes: v0.8.0
k6/x/output-kafka": v0.7.0
checksum: f4af178bb2e29862c0fc7d481076c9ba4468572903480fe9d6c999fea75f3793
# build k6 v0.50.0 with latest version of k6/x/kubernetes using a custom catalog
k6build local -k v0.50.0 -d k6/x/kubernetes \
-c /path/to/catalog.json -q
# build k6 v0.50.0 using a custom GOPROXY
k6build local -k v0.50.0 -e GOPROXY=http://localhost:80 -q
--allow-build-semvers allow building versions with build metadata (e.g v0.0.0+build).
-c, --catalog string dependencies catalog (default "https://registry.k6.io/catalog.json")
-g, --copy-go-env copy go environment (default true)
-d, --dependency stringArray list of dependencies in form package:constrains
-e, --env stringToString build environment variables (default [])
-h, --help help for local
-k, --k6 string k6 version constrains (default "*")
-o, --output string path to put the binary as an executable. (default "k6")
-p, --platform string target platform (default GOOS/GOARCH)
-q, --quiet don't print artifact's details
-f, --store-dir string object store dir (default "/tmp/k6build/store")
-v, --verbose print build process output
- k6build - Build custom k6 binaries with extensions
build a custom k6 using a remote build server
Builds custom k6 binaries using a k6build server returning the details of the binary artifact and optionally download it.
k6build remote [flags]
# build k6 v0.51.0 with k6/x/kubernetes v0.8.0 and k6/x/output-kafka v0.7.0
k6build remote -s http://localhost:8000 \
-k v0.51.0 \
-p linux/amd64 \
-d k6/x/kubernetes:v0.8.0 \
-d k6/x/output-kafka:v0.7.0
id: 62d08b13fdef171435e2c6874eaad0bb35f2f9c7
platform: linux/amd64
k6: v0.51.0
k6/x/kubernetes: v0.9.0
k6/x/output-kafka": v0.7.0
checksum: f4af178bb2e29862c0fc7d481076c9ba4468572903480fe9d6c999fea75f3793
url: http://localhost:8000/store/62d08b13fdef171435e2c6874eaad0bb35f2f9c7/download
# build k6 v0.51 with k6/x/output-kafka v0.7.0 and download as 'build/k6'
k6build remote -s http://localhost:8000 \
-p linux/amd64 \
-k v0.51.0 -d k6/x/output-kafka:v0.7.0 \
-o build/k6 -q
# check downloaded binary
build/k6 version
k6 v0.51.0 (go1.22.2, linux/amd64)
Extensions:
github.com/grafana/xk6-output-kafka v0.7.0, xk6-kafka [output]
-d, --dependency stringArray list of dependencies in form package:constrains
-h, --help help for remote
-k, --k6 string k6 version constrains (default "*")
-o, --output string path to download the custom binary as an executable.
If not specified, the artifact is not downloaded.
-p, --platform string target platform (default GOOS/GOARCH)
-q, --quiet don't print artifact's details
-s, --server string url for build server (default "http://localhost:8000")
- k6build - Build custom k6 binaries with extensions
k6 build service
Starts a k6build server
The server exposes an API for building custom k6 binaries.
The build endpoint returns the metadata of the custom binary, including an URL for downloading it, but does not return the binary itself.
This function is implemented in the /build endpoint, and supports both POST and GET methods.
POST
The POST method expects the build request in the request's body as a JSON object.
Example
curl -X POST http://localhost:8000/build -d \
'{
"k6":"v1.4.0",
"dependencies":[
{
"name":"k6/x/kubernetes",
"constraints":">v0.8.0"
}
],
"platform":"linux/amd64"
}' | jq .
{
"artifact": {
"id": "5a241ba6ff643075caadbd06d5a326e5e74f6f10",
"url": "http://localhost:9000/store/5a241ba6ff643075caadbd06d5a326e5e74f6f10/download",
"dependencies": {
"k6": "v1.4.0",
"k6/x/kubernetes": "v0.10.0"
},
"platform": "linux/amd64",
"checksum": "bfdf51ec9279e6d7f91df0a342d0c90ab4990ff1fb0215938505a6894edaf913"
}
}
GET
The GET method expects the build requests in the query parameters:
- platform: platform to build the binary for (e.g. linux/arm64). This is required
- k6: the k6 version constrains (e.g. k6=v1.2.0)
- dep: a dependency in the form name:version (e.g. dep=k6/x/faker:v0.4.0). Multple dependencies can be defined in a request.
Example
curl -X GET "http://localhost:8000/build?platform=linux/amd64&k6=v1.4.0&dep=k6/x/kubernetes:>v0.8.0" | jq .
{
"artifact": {
"id": "5a241ba6ff643075caadbd06d5a326e5e74f6f10",
"url": "http://localhost:9000/store/5a241ba6ff643075caadbd06d5a326e5e74f6f10/download",
"dependencies": {
"k6": "v1.4.0",
"k6/x/kubernetes": "v0.10.0"
},
"platform": "linux/amd64",
"checksum": "bfdf51ec9279e6d7f91df0a342d0c90ab4990ff1fb0215938505a6894edaf913"
}
}
Caching
The GET method can be used to allow caching the build results. This method returns the ETag header with the artifact's ID and sets the Cache-Control max-age parameter to the value specified in the --cache-max-age argument.
The ETag will be the same for the same dependencies, regardless of the order of the parameters, but some caching proxies rely on the URL. Therefore, to improve cacheability, the parameters should be in a consistent order. We recommend placing first platform, then k6 (if present) and finally the deps in alphabetical order. Example: plarform=linux/arm64&k6=v1.2.0&dep=k6/x/faker:v0.4.0&dep=k6/x/kafka:*
Notice that if the requests uses contrains like "*" or ">vx.y.z" for k6 or the dependencies, each build request can potentially return a different artifact if a new version is released. Therefore we recommend not setting the max-age to a large value (days) and use instead in the range of a few hours to one day, dependending on how critical is to use new versions.
The Resolve operation returns the versions that satisfy the given dependency constrains or an error if they cannot be satisfied.
For example
curl http://localhost:8000/resolve -d \
'{
"k6":"v0.50.0",
"dependencies":[
{
"name":"k6/x/kubernetes",
"constraints":">v0.8.0"
}
],
}' | jq .
{
"dependencies": {
"k6": "v0.50.0",
"k6/x/kubernetes": "v0.10.0"
},
}
The server exposes prometheus metrics at /metrics.
requests_total The total number of builds requests (counter) request_duration_seconds duration of the build request in seconds (histogram) Buckets: 0.1, 0.5, 1, 2.5, 5, 10, 20, 30, 60, 120, 300 object_store_hits_total The total number of build requests served from object store (counter) builds_total The total number of builds builds_failed_total The total number of failed builds (counter) builds_invalid_total The total number of builds with invalid parameters (counter). Includes extension/versions not available and platforms not supported. build_duration_seconds The duration of the build in seconds (histogram) Buckets: 1, 5, 10, 20, 30, 45, 60, 75, 90, 105, 120, 300
The server exposes a liveness check at /alive. This endpoint returns a response code 200 with an empty body.
Building a binary is a resource intensive task. The build server uses a lock to prevent concurrent builds of the same binary. By default, it uses a lock that works locally for a build service.
The --build-lock option allows to select a s3-backed global lock that works across instances. This lock works by creating a lock object in a s3 bucket, using the conditional put to prevent multiple instances creating it. The one creating the lock, holds it. Those that failed to acquire the lock will retry periodically until they acquire it.
To ensure the liveness of the process, the owner must uptade its lease of the lock frequently (this is done automatically by the lock implementation). If it is fails to do so, after a grace period, the lock is released. Also, there's a maximum time it can hold the lock, even if it keeps updating it. The s3-lock-* parameters allows to fine-tune this process.
Note: There are no guarantees the global lock will prevent concurrent builds, but it lowers the probability of this happing. Given that building the binary is an indenpontent operation, this poses not risk.
k6build server [flags]
# start the build server using a custom local catalog
k6build server -c /path/to/catalog.json
# start the build server using a custom GOPROXY
k6build server -e GOPROXY=http://localhost:80
# start the build server with a localstack s3 storage backend
# aws credentials are expected in the default location (e.g. env variables)
export AWS_ACCESS_KEY_ID="test"
export AWS_SECRET_ACCESS_KEY="test"
k6build server --s3-endpoint http://localhost:4566 --store-bucket k6build
--allow-build-semvers allow building versions with build metadata (e.g v0.0.0+build).
--build-lock string lock to prevent concurrent builds: 'local' or 's3' (across instances) (default "local")
--cache-max-age duration chache max-time for artifacts
-c, --catalog string dependencies catalog. Can be path to a local file or an URL. (default "https://registry.k6.io/catalog.json")
-g, --copy-go-env copy go environment (default true)
--enable-cgo enable CGO for building binaries.
-e, --env stringToString build environment variables (default [])
-h, --help help for server
-l, --log-level string log level (default "INFO")
-p, --port int port server will listen (default 8000)
--s3-bucket string s3 bucket for storing binaries
--s3-endpoint string s3 endpoint
--s3-lock-backoff duration time between retries for acquiring a lock (default 1s)
--s3-lock-grace duration grace period for renewing the lease. If the lock has not been updated before this time, it is considered expired (default 10s)
--s3-lock-lease duration time the lock is granted to the owner. The owner should renew the lock at least once before the lease expires. (default 1s)
--s3-lock-max-lease duration the maximum time a lock can be held. After this time, it is automatically released (default 3s)
--s3-region string aws region
--shutdown-timeout duration maximum time to wait for graceful shutdown (default 10s)
--store-bucket string deprecated. Use s3-bucket
--store-url string store server url (default "http://localhost:9000")
-v, --verbose print build process output
- k6build - Build custom k6 binaries with extensions
k6build object store server
Starts a k6build objectstore server.
The object server offers a REST API for storing and downloading objects.
Objects can be retrieved by a download url returned when the object is stored.
The --download-url specifies the base URL for downloading objects. This is necessary to allow downloading the objects from different machines.
k6build store [flags]
# start the server serving an external url
k6build store --download-url http://external.url
# store object from same host
curl -x POST http://localhost:9000/store/objectID -d "object content" | jq .
{
"Error": "",
"Object": {
"ID": "objectID",
"Checksum": "17d3eb873fe4b1aac4f9d2505aefbb5b53b9a7f34a6aadd561be104c0e9d678b",
"URL": "http://external.url:9000/store/objectID/download"
}
}
# download object from another machine using the external url
curl http://external.url:9000/store/objectID/download
-d, --download-url string base url used for downloading objects.
If not specified http://localhost:<port> is used
-h, --help help for store
-l, --log-level string log level (default "INFO")
-p, --port int port server will listen (default 9000)
--shutdown-timeout duration maximum time to wait for graceful shutdown (default 10s)
-c, --store-dir string object store directory (default "/tmp/k6build/store")
- k6build - Build custom k6 binaries with extensions
k6build version
k6build version [flags]
-h, --help help for version
- k6build - Build custom k6 binaries with extensions