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 all commits
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

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
Loading
Loading