Releases: grafana/k6x
v0.4.2
v0.4.1
v0.5.0-alpha.2
prerelease for v0.5.0
v0.5.0-alpha.1
Pre-release for v0.5.0
v0.4.0
k6x v0.4.0 is here 🎉!
Main new features:
- Builder Service #17
- Filter Extension Registry #20
- Build Cache Location Override #18
- Module replacement #19
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 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:
using wget
wget --content-disposition https://example.com/linux/amd64/[email protected],[email protected],k6/x/[email protected],[email protected]
using curl
curl -OJ https://example.com/linux/amd64/[email protected],[email protected],k6/x/[email protected],[email protected]
Usage from k6x
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.
using wget
wget --content-disposition https://example.com/linux/amd64/top,k6/x/faker,dashboard
using curl
curl -OJL https://example.com/linux/amd64/top,k6/x/faker,dashboard
How It Works
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:
https://example.com/linux/amd64/[email protected],[email protected],k6/x/[email protected],[email protected]
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
v0.3.1
v0.3.0
k6x v0.3.0 is here 🎉!
Main new features:
Add dependencies on the command line
In some cases, it may be useful to add dependencies on the command line without modifying the test script.
Additional dependencies and version constraints can be specified on the command line with the --with flag.
--with dependency you can specify additional dependencies and version constraints, the form of the dependency is the same as that used in the "use k6 with" pragma (practically the same as the string after the use k6 with)
k6x run --with k6/x/mock script.js
The example above adds the xk6-mock extension to the list of dependencies.
Docker Image
In certain circumstances, it can be useful to run k6x using the docker engine itself, as a drop-in replacement of the k6 docker image. Therefore, it is advisable to publish in the form of a docker image that contains the tools necessary for building (golang, git).
The szkiba/k6x docker image is available from the Docker Hub.
The k6x docker builder (--builder docker) now uses the k6x docker image instead of the xk6 docker image to build the k6 binary. This results in a significant reduction in build time. The speed increase is due to the use of persistent go cache. The k6x-cache volume is a persistent local docker volume. This is where the go cache and the go module cache are placed.
v0.2.0
k6x v0.2.0 is here 🎉!
The most important new feature in this release is the use of the installed go compiler if available. This significantly reduces the time required to create the custom k6 binary, especially from the second build onwards.
In addition, some minor fixes and modifications have been added thanks to @bandorko: