Revamp extensions docs #2030

dgzlopes · 2025-08-11T11:20:07Z

What?

This PR revamps the extensions section of our docs to properly reflect the current state of extensions after the GA release of the "automatic extensions loading" project.

Checklist

I have used a meaningful title for the PR.
I have described the changes I've made in the "What?" section above.
I have performed a self-review of my changes.
I have run the npm start command locally and verified that the changes look good.

I have made my changes in the docs/sources/k6/next folder of the documentation.

Related PR(s)/Issue(s)

https://github.com/grafana/website/pull/26929

CLAassistant · 2025-08-11T11:20:14Z

All committers have signed the CLA.

CLAassistant · 2025-08-11T11:20:15Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

dgzlopes · 2025-08-11T11:20:33Z

docs/sources/k6/next/extensions/create/_index.md


 - [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.


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

dgzlopes · 2025-08-11T11:21:00Z

docs/sources/k6/next/extensions/explore.md


-{{< /code >}}
+TBD


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

cc @heitortsergent @Lantero

dgzlopes · 2025-08-11T11:21:08Z

docs/sources/k6/next/extensions/explore.md


-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


Same as above.

dgzlopes · 2025-08-11T11:22:19Z

docs/sources/k6/next/extensions/run/_index.md

+- **Official & Community** → You can import them directly in your test. If your local binary doesn’t already include them, k6 automatically loads a compatible version when you run your test.
+- **Other** (from the ecosystem or your own) → These require building a custom k6 binary with [xk6](https://github.com/grafana/xk6).
+
+## Using automatic extension loading


I didn't get into all the pragma things, etc. If someone has the time to add it, please, go ahead.

dgzlopes · 2025-08-11T11:23:06Z

scripts/extension-registry-changed

+          .module != "go.k6.io/k6"
+          and .tier == $tier
+          and .repo.name != "xk6-kafka"
+          and .repo.name != "xk6-sse"


This is a hack. It is terrible... but I didn't want these to appear twice (in community and others).

dgzlopes · 2025-08-11T11:23:44Z

docs/sources/k6/next/extensions/explanations/extensions-registry.md

@@ -76,23 +76,6 @@ Our goal is to quickly understand the intent of the extension.

 {{< /admonition >}}

-## Extension Tiers


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

dgzlopes · 2025-08-11T11:24:34Z

docs/sources/k6/next/extensions/explanations/extension-graduation.md

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

dgzlopes · 2025-08-11T11:25:49Z

docs/sources/k6/next/extensions/_index.md


-<div class="nav-cards">


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.

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.

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.

szkiba · 2025-08-11T11:47:21Z

docs/sources/k6/next/extensions/explore.md

+| 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)                           |


szkiba · 2025-08-11T11:47:40Z

docs/sources/k6/next/extensions/explore.md

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


codebien

@dgzlopes thanks for addressing it. Generally speaking the unique issue I see is the concept between Community and Others.

As a user, they don't match my expectations, where I find the current representation more complicated, instead I would prefer:

Others should to be just Community
Community should be Cloud-Enabled Community

cc @Lantero

docs/sources/k6/next/extensions/run/_index.md

codebien · 2025-08-11T13:44:48Z

docs/sources/k6/next/extensions/_index.md


-<div class="nav-cards">


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.

docs/sources/k6/next/extensions/run/_index.md

Co-authored-by: Ivan <[email protected]>

Signed-off-by: Daniel González Lopes <[email protected]>

dgzlopes · 2025-08-12T10:12:17Z

@codebien @mstoykov I just pushed what we discussed in the call 👍

codebien · 2025-08-12T13:55:12Z

@heitortsergent we are merging this as-is right now as we need for the release. But we would much appreciate any additional reviews as this is a very draft version, and we should re-iterate on it.

Revamp extensions docs

e26de41

dgzlopes requested review from heitortsergent and a team as code owners August 11, 2025 11:20

dgzlopes requested review from pablochacin and removed request for a team August 11, 2025 11:20

dgzlopes commented Aug 11, 2025

View reviewed changes

dgzlopes requested review from codebien and Lantero August 11, 2025 11:26

szkiba reviewed Aug 11, 2025

View reviewed changes

codebien reviewed Aug 11, 2025

View reviewed changes

dgzlopes and others added 5 commits August 12, 2025 09:52

Update docs/sources/k6/next/extensions/run/_index.md

a0f37cf

Co-authored-by: Ivan <[email protected]>

Update docs/sources/k6/next/extensions/run/_index.md

71ab25b

Co-authored-by: Ivan <[email protected]>

Update docs/sources/k6/next/extensions/run/_index.md

27f90b3

Co-authored-by: Ivan <[email protected]>

Update docs/sources/k6/next/extensions/run/_index.md

bb064f7

Co-authored-by: Ivan <[email protected]>

Change structure of docs

a5180e3

Signed-off-by: Daniel González Lopes <[email protected]>

codebien added 2 commits August 12, 2025 15:48

Added missing parts to explore page

69b0813

Fix the custom binary link

04d63c5

codebien approved these changes Aug 12, 2025

View reviewed changes

codebien merged commit b926a85 into main Aug 12, 2025
6 of 7 checks passed

codebien deleted the revamp-extensions-docs branch August 12, 2025 13:56

mstoykov approved these changes Aug 12, 2025

View reviewed changes


		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

		@@ -76,23 +76,6 @@ Our goal is to quickly understand the intent of the extension.

		{{< /admonition >}}

		## Extension Tiers

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


		<div class="nav-cards">


		<div class="nav-cards">

Revamp extensions docs #2030

Revamp extensions docs #2030

Conversation

dgzlopes commented Aug 11, 2025

What?

Checklist

Related PR(s)/Issue(s)

Uh oh!

CLAassistant commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Aug 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dgzlopes Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codebien left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dgzlopes commented Aug 12, 2025

Uh oh!

codebien commented Aug 12, 2025

Uh oh!

Uh oh!

Uh oh!

CLAassistant commented Aug 11, 2025 •

edited

Loading

dgzlopes Aug 12, 2025 •

edited

Loading