Build a k6 binary using Go
Note: Not interested in setting up a Go environment? You can use Docker instead.
Before you start
- Set up Go and Git.
- Make sure that your
$PATHenvironment variable is updated so that
go versionreturns the correct version.
Given the prerequisite Go setup, installing xk6 itself requires only the following command:
$ go install go.k6.io/xk6/cmd/xk6@latest
To confirm your installation, run
which xk6 on Linux and Mac, or
where xk6 on Windows.
Make sure the command returns a valid path.
If not, check that you’ve correctly defined the
$GOPATH environment variable and that
is in your
$PATH. See the Go documentation
Building your first extension
Once installed, building a k6 binary with one or more extensions can be done with the
command as follows:
$ xk6 build latest \ --with email@example.com \ --with github.com/grafana/xk6-output-prometheus-remote
... [INFO] Build environment ready ... [INFO] Building k6 ... [INFO] Build complete: ./k6 xk6 has now produced a new k6 binary which may be different than the command on your system path! Be sure to run './k6 run <SCRIPT_NAME>' from the '...' directory.
Breaking down the xk6 command
From the xk6 documentation, the command-line usage is as follows:
xk6 build [<k6_version>] [--output <file>] [--with <module[@version][=replacement]>...] [--replace <module=replacement>...] Flags: --output specifies the new binary name [default: 'k6'] --replace enables override of dependencies for k6 and extensions [default: none] --with the extension module to be included in the binary [default: none]
The use of
--replaceshould be considered an advanced feature to be avoided unless required.
Referring back to our executed command, note that:
- We specify the version as
latest, which is also the default if we hadn’t supplied a version.
latestmeans that we’ll build using the latest source code for k6. Consider using a stable release version as a best practice unless you genuinely want the bleeding edge.
- With each
--with, we specified a full GitHub URI for the extension repository. If not specifying a version, the default is
latestonce again. Check your extension repository for stable release versions, if available, to lock in your version as we’ve done with
- We did not use the
--outputoption; therefore, our new binary is
k6within the current directory. Had we used
--output k6-extended, our binary would be named
k6-extendedwithin the current directory. If a directory is specified, then the new binary would be
k6within that directory. If a path to a non-existent file, e.g.
/tmp/k6-extended, this will be the path and filename for the binary.
./k6 version should show your build is based upon the appropriate version.
Building from a local repository
Suppose now you’ve cloned the
xk6-sql repository and want the local version included in your
custom binary? From the cloned directory, we would then use:
Based upon the command usage described in the previous section, this tells xk6 to use the current directory as the replacement for the module.
Running your extended binary
Now that we have our newly built k6 binary, we can run scripts using the functionalities of the bundled extensions.
$ ./k6 run my-script.js
Be sure to specify the binary just built in the current directory as
./k6, or else Linux/Mac could execute another k6 binary on your system path. Windows shells will first search for the binary in the current directory by default.