Skip to content
Conn3x

k6

Conn3x grade

A Conn3x circuit that installs k6, Grafana’s load testing tool, on your hosts. Each host gets a pinned k6 release from GitHub, checked against its SHA-256 before it’s unpacked, and k6 on the path. Point it at the boxes you run load tests from, such as a CI runner or a host close to the service under test.

It installs the tool and stops there. Writing and running tests is up to you.

Usage

Section titled “Usage”
module "k6" {
  source = "github.com/conn3xorg/circuit-k6?ref=v0.1.0"


  hosts                = { loadgen = "203.0.113.10" }
  ssh_private_key_file = "~/.ssh/id_ed25519"
}

Then run conn3x init and conn3x apply. A second conn3x plan says No changes.

On the host, run a test the usual way:

Terminal window
k6 run --vus 10 --duration 30s script.js

To try it on a throwaway container first, see examples/local.

Moving to a new release

Section titled “Moving to a new release”

The version and its checksums go together. Take both from the release’s checksums file:

Terminal window
v=2.3.0
curl -sSfL "https://github.com/grafana/k6/releases/download/v$v/k6-v$v-checksums.txt" | grep -E 'linux-(amd64|arm64)\.tar\.gz$'
k6_version = "2.3.0"
checksums = {
  amd64 = "39c3117b6af817592dcd0ce4242105c0a7af10948c2a425306f0be8f7a8a8ab1"
  arm64 = "5ca3433e8201da72a284aaa241a1bb5fb47f4abb4e384d39410ddd8062f49b90"
}

The plan stops on a checksum that isn’t 64 hex digits, and the apply stops on one that doesn’t match the download. Read the release notes before you move to a new major version.

What it does

Section titled “What it does”

Before the circuit runs, the conn3x_host data source reads each host’s architecture over SSH. Then, on each host:

  1. Installs curl, tar and gzip.
  2. Downloads k6-v<version>-linux-<arch>.tar.gz from the GitHub release to /opt/k6, and checks it against checksums.
  3. Unpacks it to /opt/k6/<version> and links /usr/local/bin/k6 to the binary.

It uses the release tarball rather than Grafana’s apt or rpm repository, so the version is the one you pinned and the same steps work on every distribution. k6 is one static binary, with nothing else to install.

Usage reports

Section titled “Usage reports”

By default, k6 sends anonymous usage statistics to Grafana after each run. To turn that off, pass --no-usage-report or set K6_NO_USAGE_REPORT=true where you run it. This circuit doesn’t change k6’s defaults.

What it doesn’t do

Section titled “What it doesn’t do”
  • It doesn’t run tests, schedule them or collect results. Run k6 from your own scripts or CI, and send results where you like with --out.
  • It doesn’t add k6 extensions. Those need a custom build with xk6.
  • It doesn’t keep old versions tidy. A new k6_version leaves the previous one under /opt/k6.
  • Deleting the module leaves k6 in place.

Inputs

Section titled “Inputs”
Name Type Default Description
hosts any Required Hosts to configure, by name. Each value is an address, such as "203.0.113.10", or a host object such as { address = "203.0.113.10", host_key = "ssh-ed25519 AAAA..." }. A host object can also set user, port, private_key_file and jump_hosts. The two forms can be mixed.
ssh_user string "root" User to log in as.
ssh_port number 22 SSH port.
ssh_private_key_file string null Path to a private key. When null, Conn3x uses the SSH agent.
ssh_known_hosts_file string null known_hosts file to check host keys against. When null, ~/.ssh/known_hosts. Not used for a host object with host_key.
ssh_become bool false Run commands as root through sudo. Set it when ssh_user isn’t root.
k6_version string "2.3.0" k6 release to install, without the v.
checksums map(string) SHA-256s of 2.3.0 SHA-256 of the release tarball, by amd64 and arm64. Change it with k6_version.

Outputs

Section titled “Outputs”
Name Description
k6_version k6 release installed.
k6_path /usr/local/bin/k6.

Requirements

Section titled “Requirements”

Requires Conn3x v0.7.0 or later. Hosts need to reach GitHub to download the release. k6 itself needs nothing else.

Tested on

Section titled “Tested on”

Rocky Linux 10, Fedora 45, Ubuntu 24.04 and Debian 13, with k6 2.3.0. examples/local was applied to each in a container on arm64, and CI does the same on amd64. It checks that the second plan has no changes, starts a small HTTP listener on the host, runs a k6 test of five requests against it and checks that the exported summary counts five requests and ten passed checks, then points the test at a closed port and checks k6 fails it with exit code 99. After a restart of the container, k6 version runs and the plan has no changes.

On an Ubuntu 24.04 droplet and a Rocky Linux 10 droplet with SELinux enforcing, both s-1vcpu-1gb, the circuit was applied to both hosts at once and the same check passed. After a reboot, k6 ran and the plan had no changes.

Not run: Debian 13 or Fedora 45 on a real host, arm64 on a real host.

License

Section titled “License”

MPL-2.0. See LICENSE. k6 is AGPL-3.0, and this circuit only downloads it.

Source

Section titled “Source”