Skip to content

Revamp extensions docs #2030

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Aug 12, 2025
Merged

Revamp extensions docs #2030

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e26de41
Revamp extensions docs
dgzlopes Aug 11, 2025
a0f37cf
Update docs/sources/k6/next/extensions/run/_index.md
dgzlopes Aug 12, 2025
71ab25b
Update docs/sources/k6/next/extensions/run/_index.md
dgzlopes Aug 12, 2025
27f90b3
Update docs/sources/k6/next/extensions/run/_index.md
dgzlopes Aug 12, 2025
bb064f7
Update docs/sources/k6/next/extensions/run/_index.md
dgzlopes Aug 12, 2025
a5180e3
Change structure of docs
dgzlopes Aug 12, 2025
69b0813
Added missing parts to explore page
codebien Aug 12, 2025
04d63c5
Fix the custom binary link
codebien Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 3 additions & 73 deletions docs/sources/k6/next/extensions/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,82 +1,12 @@
---
title: Extensions
description: 'The k6 extension ecosystem enables developers and testers to extend k6 to cover use cases not supported natively in the core. Explore the endless possibilities of k6 and xk6.'
description: 'The k6 extension ecosystem enables developers and testers to extend k6 to cover use cases not supported natively in the core.'
weight: 700
---

# Extensions

Expand the potential use cases for k6.
<!-- TODO: Add content -->

## Quickstart
{{< section >}}

<div class="nav-cards">
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I decided to simplify this page. There was no new info here vs. other internal pages, so I did the same we have done in a few other folders: Just show the items inside.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the plan? To add more content or to leave it as for the pushed code? I think the previous version was nicer. It would require some additional content for the new mode, but the current proposal seems not very useful.

If we don't like the previous version then I'm for deleting it and just rely on the menu in the navbar.

Copy link
Contributor Author

@dgzlopes dgzlopes Aug 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but the current proposal seems not very useful.

Fair, but... We do this in: Set up, Get started, Using k6, Examples, and a bunch of other sections in our docs.

So yeah, at least it is consistent 😄

I agree that something else here could be nicer, but the current content was extremely redundant, and this feels a bit out of scope for this PR. It would be great if the extensions team iterates on this in the future.

<a href=explore/ class="nav-cards__item nav-cards__item--guide">
<h4>🔎 Explore</h4>
<p>A list of more than 50 available extensions.</p>
</a>
<a href=build-k6-binary-using-go/ class="nav-cards__item nav-cards__item--guide">
<h4>🧩 Bundle</h4>
<p>Combine multiple extensions into a custom k6 binary.</p>
</a>
<a href=create/ class="nav-cards__item nav-cards__item--guide">
<h4>🏗️ Create</h4>
<p>Learn how to make your own k6 extension.</p>
</a>
</div>

## Custom k6 builds

With k6 extensions, you can create custom k6 binaries to support your specific reliability-testing needs.

Currently, k6 supports two ways to extend its native functionality:

- **JavaScript extensions** extend the JavaScript APIs available to your test scripts. Add support for new network protocols, improve performance compared to equivalent JS libraries, or add features.

- **Output extensions** send metrics to a custom file format or service. Add custom processing and dispatching.

- **Secret Source extensions** provide secrets to your tests.

## xk6 makes custom binaries

[xk6](https://github.com/grafana/xk6/) is command-line tool and framework written in Go. With xk6, you build custom k6 binaries that bundle one or more extensions written in Go. You have two options for creating k6 binaries: using [Go and xk6](https://grafana.com/docs/k6/<K6_VERSION>/extensions/build-k6-binary-using-go/) or [Docker](https://grafana.com/docs/k6/<K6_VERSION>/extensions/build-k6-binary-using-docker/):

{{< code >}}

```go-and-xk6
xk6 build \
--with github.com/grafana/[email protected] \
--with github.com/grafana/xk6-output-prometheus-remote
```

```docker-in-linux
docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \
--with github.com/grafana/[email protected] \
--with github.com/grafana/xk6-output-prometheus-remote
```

{{< /code >}}

<br/>

## Extension use cases

The extensions ecosystem provides endless possibilities to expand the functionality for your k6 testing. Some reasons you might want to extend k6 include the following:

- **To add support for a new network protocol**

For example, [xk6-dns](https://github.com/grafana/xk6-dns) lets users resolve DNS names to IP addresses in k6 scripts. With xk6-dns, you can assert the performance of custom DNS servers under load, and provide a way to resolve DNS names to IP addresses using a specific DNS server.

- **To incorporate a client library for test dependency**

Everyone wants to run their services in Kubernetes these days. With [xk6-kubernetes](https://github.com/grafana/xk6-kubernetes), your JavaScript tests can interface directly with Kubernetes resources using functionality typically restricted to kubectl. Prepare isolated Namespaces for each test run, or inject environment variables as ConfigMaps.

- **To format and send metrics to the output of your choice**

Suppose your company has consolidated its observability metrics into Prometheus. Use [xk6-output-prometheus-remote](https://github.com/grafana/xk6-output-prometheus-remote) to publish your k6 test metrics to Prometheus as well!

- **To improve script performance and efficiency**

Perhaps your company uses OpenTelemetry to trace service requests through layers of microservices. Using [xk6-distributed-tracing](https://github.com/grafana/xk6-distributed-tracing), you can update the http client to link your test requests as the origin for your traces—no need to add JavaScript code to supply the required trace headers.

Next, [Explore the available extensions](https://grafana.com/docs/k6/<K6_VERSION>/extensions/explore) to see how you can expand your use of k6 right now.
11 changes: 5 additions & 6 deletions docs/sources/k6/next/extensions/create/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
---
title: 'Create a k6 extension'
menuTitle: 'Create an extension'
title: 'Create a new extension'
menuTitle: 'Create a new extension'
description: 'Creating k6 extensions does not have to be a daunting task, but there are some prerequisites to succeed.'
weight: 04
---

# Create a k6 extension
# Create a new k6 extension

If you find a gap in your testing process that no k6 extension can fix,
consider building your own extension.

These tutorials show you how to create custom JavaScript and output extensions.
consider building your own extension. Use the tutorials below to get started.

- [Create a JavaScript extension](https://grafana.com/docs/k6/<K6_VERSION>/extensions/create/javascript-extensions) to extend the JavaScript functionality of your script or add support for a new network protocol to test.
- [Create an Output extension](https://grafana.com/docs/k6/<K6_VERSION>/extensions/create/output-extensions) to process the metrics emitted by k6 or publish them to unsupported backend stores.
- [Create a Secret Source extension](https://grafana.com/docs/k6/<K6_VERSION>/extensions/create/secret-source_extensions) to provide secrets to your k6 script at runtime.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not related... but small enough to add here.


## Necessary knowledge

Expand Down
56 changes: 0 additions & 56 deletions docs/sources/k6/next/extensions/explanations/extension-graduation.md
View file
Open in desktop
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I took the freedom to remove this, bc with automatic extension resolution, it felt deprecated.

This file was deleted.

17 changes: 0 additions & 17 deletions docs/sources/k6/next/extensions/explanations/extensions-registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,23 +76,6 @@ Our goal is to quickly understand the intent of the extension.

{{< /admonition >}}

## Extension Tiers
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this collides with our latest takes on the topic.


Extensions come from multiple sources.
To help distinguish extensions, we're now categorizing each extension into a _tier_.
Each tier definition is as follows:

- **Official Extensions**

_Official extensions_ are those owned and maintained by Grafana Labs.
They will have official documentation and have support provided by members of the Grafana organization.

- **Community Extensions**

_Community extensions_ are created and maintained by an individual or group from the community at large.
These have no implied warranty or level of support.
The Grafana team will make best-effort assistance to keep popular projects in compliance.

## Potential for De-listing

Given our desire to provide the best developer experience when using k6, we reserve the right to de-list any extension we deem is no longer maintaining standards.
Expand Down
101 changes: 19 additions & 82 deletions docs/sources/k6/next/extensions/explore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,94 +1,39 @@
---
title: 'Explore k6 extensions'
title: 'Explore extensions'
menuTitle: 'Explore extensions'
description: 'Explore the k6 extension ecosystem to find extensions that meet your requirements.'
weight: 01
---

# Explore k6 extensions
# Explore extensions

With over 50 available extensions, the k6 extension ecosystem has many options to meet your requirements and help you incorporate new protocol access, embed a particular client, or improve your test performance. Extensions are developed both by the k6 developers and by the open-source developer community.
There are three categories of extensions:

Extensions are composable; you can combine any extensions, or mix and match different test cases. You can use [Go and xk6](https://grafana.com/docs/k6/<K6_VERSION>/extensions/build-k6-binary-using-go/) or [Docker](https://grafana.com/docs/k6/<K6_VERSION>/extensions/build-k6-binary-using-docker/) to build your custom k6 binary:
| Category | Maintainer | Audited | Cloud support | How to use them |
| ------------- | ----------------------------------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Official** | Grafana Labs | ✅ Yes | ✅ Yes | [Import them in your test](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-automatic-extension-loading) |
| **Community** | Community | ✅ Yes | ⚠️ Partial\* | [Import them in your test](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-automatic-extension-loading) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| **Community** | Community | ✅ Yes | ⚠️ Partial\* | [Import them in your test](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-automatic-extension-loading) |
| **Featured** | Community | ✅ Yes | ⚠️ Partial\* | [Import them in your test](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-automatic-extension-loading) |

| **Other** | Community | ❌ No | ⚠️ Partial\* | [Build a custom k6 binary](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-other-extensions) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| **Other** | Community | ❌ No | ⚠️ Partial\* | [Build a custom k6 binary](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-other-extensions) |
| **Community** | Community | ❌ No | ⚠️ Partial\* | [Build a custom k6 binary](https://grafana.com/docs/k6/<K6_VERSION>/extensions/run/#using-other-extensions) |


{{< code >}}
\* *Partial* means that they can be used in the CLI with the `--local-execution` mode. Also, on Private Load Zones if a custom image is build. They don't work on Grafana Cloud k6 Public Load Zones.

```go-and-xk6
xk6 build \
--with github.com/grafana/[email protected] \
--with github.com/grafana/xk6-output-prometheus-remote
```

```docker-in-linux
docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \
--with github.com/grafana/[email protected] \
--with github.com/grafana/xk6-output-prometheus-remote
```
## Official extensions

{{< /code >}}
TBD
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How should we handle this? Point to Cloud docs? Duplicate them here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @heitortsergent @Lantero


<br/>
## Community extensions

Use the table to explore the many extensions. Questions? Feel free to join the discussion about extensions in the [k6 Community Forum](https://community.grafana.com/c/grafana-k6/extensions/82).
TBD
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above.


## Official extensions
## Other extensions
{{< admonition type="caution" >}}

These are the official extensions, which are owned and maintained by the Grafana organization.
The extensions listed below are not maintained nor audited by Grafana Labs.

<div class="nav-cards">
<a href="https://github.com/grafana/xk6-client-prometheus-remote" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-client-prometheus-remote</h4>
<p>Test Prometheus Remote Write-compatible endpoints</p>
</a>
<a href="https://github.com/grafana/xk6-dashboard" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-dashboard</h4>
<p>Create a web-based metrics dashboard</p>
</a>
<a href="https://github.com/grafana/xk6-disruptor" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-disruptor</h4>
<p>Inject faults to test 💣</p>
</a>
<a href="https://github.com/grafana/xk6-exec" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-exec</h4>
<p>Run external commands</p>
</a>
<a href="https://github.com/grafana/xk6-faker" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-faker</h4>
<p>Generate fake data in your tests</p>
</a>
<a href="https://github.com/grafana/xk6-kubernetes" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-kubernetes</h4>
<p>Interact with Kubernetes clusters</p>
</a>
<a href="https://github.com/grafana/xk6-output-influxdb" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-output-influxdb</h4>
<p>Export results to InfluxDB v2</p>
</a>
<a href="https://github.com/grafana/xk6-sql" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-sql</h4>
<p>Load-test SQL Servers</p>
</a>
<a href="https://github.com/grafana/xk6-sql-driver-mysql" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-sql-driver-mysql</h4>
<p>xk6-sql driver extension for MySQL database support</p>
</a>
<a href="https://github.com/grafana/xk6-sql-driver-postgres" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-sql-driver-postgres</h4>
<p>xk6-sql driver extension for Postgres database support</p>
</a>
<a href="https://github.com/grafana/xk6-sql-driver-sqlite3" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-sql-driver-sqlite3</h4>
<p>xk6-sql driver extension for SQLite v3 database support</p>
</a>
<a href="https://github.com/grafana/xk6-ssh" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-ssh</h4>
<p>Use SSH connections in your tests</p>
</a>
</div>

## Community extensions
{{< /admonition >}}

These are the community extensions, which are owned by our community members.
The Grafana team makes a best-effort assistance to keep these extensions in compliance.
Many other extensions, maintained by members of the k6 community are available in [GitHub](https://github.com/topics/xk6). You can find some of them listed below. All these fullfil our list of [minimum requirements](https://grafana.com/docs/k6/<K6_VERSION>/extensions/explanations/extensions-registry/#registry-requirements).

<div class="nav-cards">
<a href="https://github.com/prmuthu/xk6-amqp" target="_blank" class="nav-cards__item nav-cards__item--guide">
Expand Down Expand Up @@ -175,10 +120,6 @@ The Grafana team makes a best-effort assistance to keep these extensions in comp
<h4>xk6-interpret</h4>
<p>Interpret Go code</p>
</a>
<a href="https://github.com/mostafa/xk6-kafka" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-kafka</h4>
<p>Load test Apache Kafka. Includes support for Avro messages.</p>
</a>
<a href="https://github.com/oleiade/xk6-kv" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-kv</h4>
<p>Share key-value data between VUs</p>
Expand Down Expand Up @@ -299,10 +240,6 @@ The Grafana team makes a best-effort assistance to keep these extensions in comp
<h4>xk6-sql-driver-sqlserver</h4>
<p>xk6-sql driver extension for Microsoft SQL Server database support</p>
</a>
<a href="https://github.com/phymbert/xk6-sse" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-sse</h4>
<p>Server Sent Event</p>
</a>
<a href="https://github.com/walterwanderley/xk6-stomp" target="_blank" class="nav-cards__item nav-cards__item--guide">
<h4>xk6-stomp</h4>
<p>Client for STOMP protocol</p>
Expand Down
Loading
Loading