Extensions on Grafana Labs

Explore extensions

Mon, 21 Sep 2026 15:16:28 +0000

Explore extensions

Extensions can be used to extend the core k6 features to fit your performance-testing use cases. There are two main categories of extensions: official and community.

Official extensions

These are extensions owned and maintained by Grafana Labs, with support for a wide range of versions.

Extension	Description	Versions
xk6-dns	DNS resolution and lookups in your tests	v1.0.1, v1.0.0
xk6-faker	Generate fake data in your tests	v0.4.4, v0.4.3, v0.4.2, v0.4.1, v0.4.0
xk6-icmp	ICMP protocol support for k6	v0.2.0, v0.1.0
xk6-mqtt	MQTT protocol support for k6	v0.2.0, v0.1.1
xk6-redis	Extension for Redis database	v0.3.6
xk6-sql	Load-test SQL Servers	v1.0.5, v1.0.4, v1.0.3, v1.0.2, v1.0.1, v1.0.0
xk6-sql-driver-mysql	xk6-sql driver extension for MySQL database support	v0.2.1, v0.2.0, v0.1.0
xk6-sql-driver-postgres	xk6-sql driver extension for Postgres database support	v0.1.1, v0.1.0
xk6-ssh	Use SSH connections in your tests	v0.1.3, v0.1.2, v0.1.1, v0.1.0
xk6-tcp	TCP protocol support for k6	v0.2.0
xk6-docs	CLI k6 docs for AI agents and users. It comes with an agent skill to help AI agents to write k6 scripts with best practices.	v0.0.8, v0.0.7, v0.0.6, v0.0.5, v0.0.1
xk6-subcommand-explore	Explore k6 extensions for Automatic Resolution	v1.0.0

Community extensions

These are extensions developed by the community, with support for specific versions.

Note
We’re working on a process for community folks to submit their extensions.

Extension	Description	Versions
xk6-disruptor	Add fault injection capabilities to k6, following the chaos engineering principles.	v0.3.17
xk6-kafka	Load test Apache Kafka. Includes support for Avro messages.	v1.0.0
xk6-kubernetes	A k6 extension for interacting with Kubernetes clusters while testing.	v0.10.3
xk6-loki	Test Grafana Loki log ingestion endpoints	v1.0.1, v1.0.0
xk6-msgpack	k6 MessagePack extension	v0.0.3
xk6-client-prometheus-remote	Test Prometheus Remote Write-compatible endpoints	v0.3.2
xk6-sql-driver-azuresql	xk6-sql driver extension for Microsoft Azure SQL database support	v0.1.1, v0.1.0
xk6-sql-driver-clickhouse	xk6-sql driver extension for ClickHouse database support	v0.1.1, v0.1.0
xk6-sql-driver-sqlserver	xk6-sql driver extension for Microsoft SQL Server database support	v0.1.1, v0.1.0
xk6-sse	Server Sent Event	v0.1.11, v0.1.10
xk6-tls	TLS certificates validation and inspection	v0.1.0
xk6-client-tracing	This extension provides k6 with the required functionality required to load test distributed tracing backends.	v0.0.9
xk6-subcommand-httpbin	Run a local httpbin server from k6	v1.0.1, v1.0.0

Use extensions

There are two ways to use extensions when running a k6 test script.

Automatic extension resolution

You can use these extensions without any additional configuration. k6 automatically resolves and loads them when you use them:

JavaScript extensions are loaded when you import them in your test script.
Subcommand extensions are loaded when you invoke them using k6 x <subcommand>. Refer to subcommand extensions for details.

Custom k6 binary

If you have developed your own k6 extension or want to use an extension that’s not available through automatic extension resolution, you have to build a custom k6 binary. The process involves using the xk6 tool to compile k6 with your desired extensions included. Custom binaries give you the flexibility to incorporate any extension from the k6 ecosystem.

Refer to build a custom k6 binary guide to learn how to create your own k6 binary with custom extensions.

Caution
Many other extensions maintained by members of the k6 ecosystem are available in GitHub. These extensions aren’t maintained nor audited by Grafana Labs.

Run a test with extensions

Mon, 21 Sep 2026 15:16:28 +0000

Run a test with extensions

There are two different ways to run your k6 test script depending on the k6 extension you want to use: using the automatic extension resolution, or building a custom k6 binary.

Before you begin

Install k6 v1.2.0 or higher.

Use automatic extension resolution

It’s as easy as importing them. Example with xk6-faker:

import faker from 'k6/x/faker';

export default function () {
  console.log(faker.person.firstName());
}

Then, you can run your script as usual, and k6 automatically detects the extension and loads it:

k6 run script.js

Shell tab-completion also triggers automatic extension resolution. When you press Tab after typing an extension import path, k6 provisions the extension if it isn’t already available.

Limitations

Only works with Official and Community extensions.
Output extensions aren’t supported.
Running scripts from stdin isn’t supported.
Only files with extensions .js, .ts or .tar can be used.

Disable automatic extension resolution

You can disable this feature by setting the environment variable K6_AUTO_EXTENSION_RESOLUTION to false. If provided, the previous example fails because k6 can’t load the extension dynamically.

K6_AUTO_EXTENSION_RESOLUTION=false k6 run test.js

Use extensions with a custom k6 binary

To run other extensions (including ones you create), you need to build a custom k6 binary with xk6.

You can do this locally with Go or use the xk6 Docker image.

go-and-xk6

docker-in-linux

xk6 build \
  --with github.com/grafana/xk6-sql@v0.0.1 \
  --with github.com/grafana/xk6-output-influxdb

docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \
  --with github.com/grafana/xk6-sql@v0.0.1 \

For more details, refer to:

Create a k6 extension

Mon, 21 Sep 2026 15:16:28 +0000

Create a k6 extension

If you find a gap in your testing process that no k6 extension can fix, consider building your own extension. Use the tutorials below to get started.

Create a JavaScript extension to extend the JavaScript functionality of your script or add support for a new network protocol to test.
Create an Output extension to process the metrics emitted by k6 or publish them to unsupported backend stores.
Create a Secret Source extension to provide secrets to your k6 script at runtime.
Create a Subcommand extension to add custom CLI commands under the k6 x namespace.

Necessary knowledge

Anyone who can use the command line to edit files and install software should be able to follow along. But, if you want to create an extension for more than the purposes of demonstration, there’s some background knowledge you should have:

You should be familiar with both Go(lang), JavaScript, and their tooling
You should understand how the Go-to-JavaScript bridge works within k6

Note
If you maintain a public xk6 repository and wish to have your extension listed in our registry, be sure to review the requirements.

Avoid unneeded work

These actions may save you the trouble of building a whole new extension when its not needed.

Confirm that a similar extension doesn’t already exist for your use case. Take a look at the Extensions listing and the xk6 topic on GitHub.
Prefer generic solutions. For example, if you can test a system with a generic protocol like MQTT, prefer xk6-mqtt over a new extension for some custom protocol.
Lean toward writing pure JavaScript libraries over building an extension in Go. A JavaScript library will be better supported, more straightforward, and reusable than an extension.

Submit an extension

Mon, 21 Sep 2026 15:16:28 +0000

Submit an extension

Extensions are a core part of the k6 ecosystem, providing capabilities not available in the k6 core. Adding your extension to the registry makes it available to all k6 users, in open-source and Grafana Cloud k6.

There are two main categories of extensions:

Official: Owned and maintained by Grafana Labs.
Community: Developed by the community. Anyone can contribute.

Submit a Community extension when your project fills a gap not covered by k6 or existing extensions.

Before you start

Read the contribution guidelines in grafana/k6-extension-registry — they are the authoritative source for the exact registry file format, field names, and naming conventions. The requirements your extension repository must meet are at extensions registry requirements. Read both before submitting.

If something in the repository documentation is unclear, open an issue asking for clarification.

Extension prerequisites

Your extension repository must meet a minimum bar before you submit. The full list is in the registry repository, but at a minimum your extension must have:

A LICENSE file using an allowed license
A README that explains what the extension does and how to use it
A valid go.mod
At least one runnable example in an examples folder
At least one versioned release
A GitHub workflow with golangci-lint running on every pull request and every merge on the main branch

All of these requirements are automatically checked by the xk6 lint --preset community command.

Submissions that don’t meet these requirements will fail automated checks. Don’t rely on a reviewer to catch missing prerequisites.

Run the checks locally first

The registry includes a Makefile that lets you run the automated checks on your machine. Always do this before opening a pull request. CI does not run automatically on new pull requests — a maintainer must manually allow it. Running checks locally catches failures early and avoids wasting that trigger on a submission that would have failed immediately.

Submission steps

Fork grafana/k6-extension-registry.
Add your extension to the registry file, following the format documented in the repository.
Open a pull request using the provided pull request template. Fill it out completely.

What happens after you open a pull request

Automated checks

A maintainer will trigger the automated checks if the submission is legitimate — meaning it fills a clear product gap or adds a feature, with no evidence of user security risks or harassment.

Once triggered, the checks validate your registry entry and your extension repository against the documented requirements. Human review does not begin until all automated checks pass. If checks fail, consult the check output and the documentation linked above, fix the issues, and push — a maintainer will re-trigger CI.

Maintainer review

Once checks pass, a maintainer will manually review your extension repository, not just the registry entry. The key question is whether the extension is genuinely useful to the k6 community, and the overall quality and trustworthiness of the project.

Passing automated checks does not guarantee acceptance. They are a necessary condition, not a sufficient one.

There is no guaranteed review turnaround time. Maintainers actively monitor the submission queue. There is no need to follow up — any comments or decisions will appear directly on the pull request.

Reviewers may close pull requests that appear stale.

What reviewers may ask or decide

Accepted — your extension is merged into the registry and will be available soon to k6 local and Cloud runs.
Changes requested — address the feedback on your registry entry or extension repository before the review continues.
Rejected — the extension does not meet the criteria at this time. The maintainer will explain why. If circumstances change, you are welcome to open a new submission.

Ongoing responsibilities

When you list an extension, you take on its basic maintenance over time:

Security vulnerabilities: Address significant security issues using your best judgment. There is no formal response SLA, but known vulnerabilities left unaddressed may result in removal from the registry.
k6 compatibility: New k6 versions ship regularly. Watch the grafana/k6 repository on GitHub for release notifications and keep your extension compatible.
User issues: Support and respond to issues filed against your extension repository.

Decommission

If you can no longer maintain the extension, open a pull request removing it from the registry. If that is not practical, opening an issue or leaving a clear signal on the registry repository is enough — maintainers just need to know.

Additional decommissioning cases may apply. For more details, refer to the Decommission an extension guide.

Add a new version

Mon, 21 Sep 2026 15:16:28 +0000

Add a new version

When a new version is released, the registry doesn’t automatically include it. This is by design, to prevent unexpected behavior.

Process

To make a new version of your extension available in the registry, open a pull request to grafana/k6-extension-registry updating your extension entry with the new version.

If you don’t update the registry, the new version won’t be available to k6 users through automatic extension resolution or Grafana Cloud k6.

Decommission an extension

Mon, 21 Sep 2026 15:16:28 +0000

Decommission an extension

This page covers the decommissioning process for k6 extensions and explains what extension owners and users can expect.

Decommissioning applies to two scenarios:

Single version — a specific release is retired, for example when it reaches end of life or has a critical security issue.
Entire extension — the extension as a whole is retired.

Communication

The k6 core team aims to notify affected users and owners before any removal when possible. The team tries to provide known alternatives and add removal notices directly to the registry listings.

Notifications may come through:

A dedicated section in the release notes
A dedicated section or page in the k6 official docs
An issue on the original extension’s repository

Official extensions

Official extensions follow the same support process and timelines as the k6 core product.

Extensions are first marked as deprecated, giving users advance notice and a clear migration path. Support is only dropped upon the release of a subsequent major version.

Community extensions

Community extensions are maintained by their owners. Owners are encouraged to follow the same notice process as official extensions and to notify the k6 team to update the registry listing.

The k6 core team may remove a community extension or specific version from the registry at any time if it no longer meets the registry criteria.

Exceptions for immediate removal

The k6 core team may remove an extension immediately, without a grace period, when required by:

A security vulnerability with critical severity
A legal or licensing obligation
A critical safety concern

In these cases, the k6 core team will communicate the removal as soon as possible, including the reason and any available mitigation or alternative.