The k6x builder service is an HTTP service that generates a k6 binary with the extensions specified in the request. The service is included in the k6x binary, so it can be started using the k6x service command.
The k6x builder service can be used independently, from the command line (e.g. using curl or wget commands), from a web browser, or from different subcommands of the k6x launcher as a builder called service.
Usage from the command line
The k6 binary can be easily built using wget , curl or other command-line http client by retrieving the appropriate builder service URL:
The builder service can be used from k6x using the --builder service flag:
k6x run --builder service script.js
k6x expects the address of the builder service in the environment variable called K6X_BUILDER_SERVICE. There is currently no default, it must be specified.
Simplified command line usage
In order to simplify use from the command line, the service also accepts version dependencies in any order. In this case, after unlocking the latest versions and sorting, the response will be an HTTP redirect.
The service serves HTTP GET requests, with a well-defined path structure:
htps://example.com/goos/goarch/dependency-list
Where goos is the usual operating system name in the go language (e.g. linux, windows, darwin), goarch is the usual processor architecture in the go language (e.g. amd64, arm64). The dependency-list is a comma-separated list of dependencies, in the following form:
name@version
Where name is the name of the dependency and version is the version number according to semver (with an optional leading v character). The first item in the list is always the dependency named k6, and the other items are sorted alphabetically by name. For example:
Based on the platform parameters (goos, goarch) and dependencies, the service prepares the k6 binary.
Since the response (the k6 binary) depends only on the request path, it can be easily cached. The service therefore sets a sufficiently long caching period (at least one year) in the response, as well as the usual cache headers (e.g. ETag). By placing a caching proxy in front of the service, it can be ensured that the actual k6 binary build takes place only once for each parameter combination.
The advantage of the solution is that the k6 binary is created on the fly, only for the parameter combinations that are actually used. Since the service preserves the go cache between builds, a specific build happens quickly enough.
Filter Extension Registry
In certain runtime environments, the use of arbitrary extensions is not allowed. There is a need to limit the extensions that can be used.
This use case can be solved most flexibly by narrowing down the extension registry. The content of the extension registry can be narrowed using a jmespath syntax filter expression. Extensions can be filtered based on any property.
allow only officially supported extensions
k6x --filter "[?contains(tiers,'Official')]" run script.js
allow only cloud enabled extensions
k6x --filter "[?cloudEnabled == true]" run script.js
Build Cache Location Override
Reusable artifacts (k6 binary, HTTP responses) are stored in the subdirectory k6x under the directory defined by the XDG_CACHE_HOME environment variable. The default of XDG_CACHE_HOME depends on the operating system (Windows: %LOCALAPPDATA%\cache, Linux: ~/.cache, macOS: ~/Library/Caches). The default cache directory now can be changed using the K6X_CACHE_DIR environment variable or the --cache-dir flag.
Module Replacement
In some cases, it can be useful to use another path instead of the module path registered in the extension registry. For example, using a forked repository, or using a local file-system path in the case of a native builder. These use cases can be solved by the module replacement feature.
Usage:
--replace name=path replaces the module path, where name is the dependency/module name and path is a remote module path (version should be appended with @) or an absolute local file-system path (a path starting with . can also be used, which will be resolved to an absolute path). It implies the use of the native builder (--builder native) and clean flag (--clean)
with local file-system path
k6x --replace k6/x/faker=../xk6-faker run script.js
with remote path
k6x --replace k6/x/faker=github.com/my-user/xk6-faker@latest run script.js
Main new features:
Builder Service
The k6x builder service is an HTTP service that generates a k6 binary with the extensions specified in the request. The service is included in the k6x binary, so it can be started using the
k6x servicecommand.The k6x builder service can be used independently, from the command line (e.g. using
curlorwgetcommands), from aweb browser, or from different subcommands of the k6x launcher as a builder calledservice.Usage from the command line
The k6 binary can be easily built using wget , curl or other command-line http client by retrieving the appropriate builder service URL:
using wget
using curl
Usage from k6x
The builder service can be used from k6x using the
--builder serviceflag:k6x expects the address of the builder service in the environment variable called
K6X_BUILDER_SERVICE. There is currently no default, it must be specified.Simplified command line usage
In order to simplify use from the command line, the service also accepts version dependencies in any order. In this case, after unlocking the latest versions and sorting, the response will be an HTTP redirect.
using wget
using curl
How It Works
The service serves
HTTP GETrequests, with a well-defined path structure:Where
goosis the usual operating system name in the go language (e.g.linux,windows,darwin),goarchis the usual processor architecture in the go language (e.g.amd64,arm64). Thedependency-listis a comma-separated list of dependencies, in the following form:Where
nameis the name of the dependency andversionis the version number according to semver (with an optional leadingvcharacter). The first item in the list is always the dependency namedk6, and the other items are sorted alphabetically by name. For example:Based on the platform parameters (
goos,goarch) and dependencies, the service prepares the k6 binary.Since the response (the k6 binary) depends only on the request path, it can be easily cached. The service therefore sets a sufficiently long caching period (at least one year) in the response, as well as the usual cache headers (e.g.
ETag). By placing a caching proxy in front of the service, it can be ensured that the actual k6 binary build takes place only once for each parameter combination.The advantage of the solution is that the k6 binary is created on the fly, only for the parameter combinations that are actually used. Since the service preserves the go cache between builds, a specific build happens quickly enough.
Filter Extension Registry
In certain runtime environments, the use of arbitrary extensions is not allowed. There is a need to limit the extensions that can be used.
This use case can be solved most flexibly by narrowing down the extension registry. The content of the extension registry can be narrowed using a jmespath syntax filter expression. Extensions can be filtered based on any property.
allow only officially supported extensions
allow only cloud enabled extensions
Build Cache Location Override
Reusable artifacts (k6 binary, HTTP responses) are stored in the subdirectory
k6xunder the directory defined by theXDG_CACHE_HOMEenvironment variable. The default ofXDG_CACHE_HOMEdepends on the operating system (Windows:%LOCALAPPDATA%\cache, Linux:~/.cache, macOS:~/Library/Caches). The default cache directory now can be changed using theK6X_CACHE_DIRenvironment variable or the--cache-dirflag.Module Replacement
In some cases, it can be useful to use another path instead of the module path registered in the extension registry. For example, using a forked repository, or using a local file-system path in the case of a native builder. These use cases can be solved by the module replacement feature.
Usage:
--replace name=pathreplaces the module path, wherenameis the dependency/module name andpathis a remote module path (version should be appended with@) or an absolute local file-system path (a path starting with.can also be used, which will be resolved to an absolute path). It implies the use of thenativebuilder (--builder native) and clean flag (--clean)with local file-system path
with remote path