diff --git a/docs/sources/k6/next/extensions/_index.md b/docs/sources/k6/next/extensions/_index.md index 3c274945b3..9ef78d94f4 100644 --- a/docs/sources/k6/next/extensions/_index.md +++ b/docs/sources/k6/next/extensions/_index.md @@ -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. + -## Quickstart +{{< section >}} - - -## 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//extensions/build-k6-binary-using-go/) or [Docker](https://grafana.com/docs/k6//extensions/build-k6-binary-using-docker/): - -{{< code >}} - -```go-and-xk6 -xk6 build \ - --with github.com/grafana/xk6-sql@v0.0.1 \ - --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/xk6-sql@v0.0.1 \ - --with github.com/grafana/xk6-output-prometheus-remote -``` - -{{< /code >}} - -
- -## 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//extensions/explore) to see how you can expand your use of k6 right now. diff --git a/docs/sources/k6/next/extensions/create/_index.md b/docs/sources/k6/next/extensions/create/_index.md index 912901e0c5..d223c2e476 100644 --- a/docs/sources/k6/next/extensions/create/_index.md +++ b/docs/sources/k6/next/extensions/create/_index.md @@ -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//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//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//extensions/create/secret-source_extensions) to provide secrets to your k6 script at runtime. ## Necessary knowledge diff --git a/docs/sources/k6/next/extensions/explanations/extension-graduation.md b/docs/sources/k6/next/extensions/explanations/extension-graduation.md deleted file mode 100644 index 1a8e4063e4..0000000000 --- a/docs/sources/k6/next/extensions/explanations/extension-graduation.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Extension Graduation -description: Some extensions are created with the intent to become a part of core of k6. -weight: 03 ---- - -# Extension Graduation - -Some _Go_ extensions may one day be available within the k6 binary. -These select extensions pass through different phases to become core functionality. - -This graduation process benefits both users and developers. -k6 users can access new features and provide feedback to influence its developments. -k6 developers meanwhile can iterate quickly and respond to feedback without worrying about breaking changes. - -A _core-bound_ extension passes through the following phases: -![Extension graduation](/media/docs/k6-oss/extension-graduation.png) - -### Extension - -Most extensions in the k6 ecosystem remain _extensions_ requiring [xk6](https://github.com/grafana/xk6) to incorporate the custom functionality. -These extensions might be provided by Grafana or by the community, and _may_ be included in the [Extensions Registry](https://grafana.com/docs/k6//extensions/explore). - -{{< admonition type="note" >}} - -Only Grafana-controlled extensions may progress beyond the _extension_ phase to become _experimental_ or _core modules_. - -{{< /admonition >}} - -### Experimental Module - -This phase is the first exposure to core k6. -The extension is still maintained outside the core of k6 but imported as a Go module, no longer requiring xk6. - -Once an extension is promoted as an _experimental module_, the extension will be removed from the [extension listing](https://grafana.com/docs/k6//extensions/explore). -At this time, documentation for the functionality will be provided in [k6 API](https://grafana.com/docs/k6//javascript-api/k6-experimental) and [output](https://grafana.com/docs/k6//results-output/real-time) for _JavaScript_ and _Output_ extensions, respectively. - -There should be a reasonably high degree of quality and stability at this point. -This phase makes the feature accessible to more users, which in turn gives k6 developers more chances to receive feedback. -The key will be to achieve a balance between usability and stability. - -{{< admonition type="caution" >}} - -Not all experimental modules will progress to become a core module! -The k6 team reserves the right to discontinue and remove any experimental module if is no longer deemed desirable. - -{{< /admonition >}} - -### Core Module - -The stabilized feature is now part of the standard k6 product as a built-in module. -An extension may be in the _experimental module_ phase for an extended time before progressing as a core module. - -The module code is in the main k6 repository, with the old extension repository archived. -Options from the _experimental module_ phase are deprecated and removed after two k6 releases, -providing time for users to upgrade scripts for the new module. diff --git a/docs/sources/k6/next/extensions/explanations/extensions-registry.md b/docs/sources/k6/next/extensions/explanations/extensions-registry.md index db9cd2cd5b..dd1b6f93d7 100644 --- a/docs/sources/k6/next/extensions/explanations/extensions-registry.md +++ b/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 - -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. diff --git a/docs/sources/k6/next/extensions/explore.md b/docs/sources/k6/next/extensions/explore.md index 1fa0a990db..662494021b 100644 --- a/docs/sources/k6/next/extensions/explore.md +++ b/docs/sources/k6/next/extensions/explore.md @@ -1,336 +1,67 @@ --- -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. +## Supported by automatic extension resolution -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//extensions/build-k6-binary-using-go/) or [Docker](https://grafana.com/docs/k6//extensions/build-k6-binary-using-docker/) to build your custom k6 binary: +These extensions can be used in your test without any additional configuration. They are automatically resolved and loaded by k6 when you [import them in your test script](https://grafana.com/docs/k6//extensions/run/#using-automatic-extension-loading). -{{< code >}} +We have two categories of extensions: -```go-and-xk6 -xk6 build \ - --with github.com/grafana/xk6-sql@v0.0.1 \ - --with github.com/grafana/xk6-output-prometheus-remote -``` +| Category | Maintainer | Audited | Cloud support | +| ------------- | ----------------------------------- | ------- | ------------- | +| **Official** | Grafana Labs | ✅ Yes | ✅ Yes | +| **Community** | Community | ✅ Yes | ⚠️ Partial\* | -```docker-in-linux -docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \ - --with github.com/grafana/xk6-sql@v0.0.1 \ - --with github.com/grafana/xk6-output-prometheus-remote -``` +\* *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. -{{< /code >}} +### Official extensions -
+| Extension | Description | Versions | +| --------- | ----------- | -------- | +| [xk6-client-prometheus-remote](https://github.com/grafana/xk6-client-prometheus-remote) | Test Prometheus Remote Write-compatible endpoints | 0.3.2 | +| [xk6-faker](https://github.com/grafana/xk6-faker) | Generate fake data in your tests | 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4 | +| [xk6-loki](https://github.com/grafana/xk6-loki) | Test Grafana Loki log ingestion endpoints | 1.0.0, 1.0.1 | +| [xk6-sql](https://github.com/grafana/xk6-sql) | Test SQL servers | 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5 | +| [xk6-sql-driver-mysql](https://github.com/grafana/xk6-sql-driver-mysql) | SQL driver for MySQL | 0.1.0, 0.2.0, 0.2.1 | +| [xk6-sql-driver-postgres](https://github.com/grafana/xk6-sql-driver-postgres) | SQL driver for Postgres | 0.1.0, 0.1.1 | +| [xk6-ssh](https://github.com/grafana/xk6-ssh) | Use SSH connections in your tests | 0.1.0, 0.1.1, 0.1.2, 0.1.3 | -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). +### Community extensions -## Official extensions +{{< admonition type="note" >}} -These are the official extensions, which are owned and maintained by the Grafana organization. +We are working on process for community folks to submit their extensions to be included here. - +{{< /admonition >}} -## Community extensions +| Extension | Description | Versions | +| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------- | +| [xk6-kafka](https://github.com/mostafa/xk6-kafka) | Load test Apache Kafka | 1.0.0 | +| [xk6-sql-driver-azuresql](https://github.com/grafana/xk6-sql-driver-azuresql) | SQL driver for AzureSQL | 0.1.0, 0.1.1 | +| [xk6-sql-driver-clickhouse](https://github.com/grafana/xk6-sql-driver-clickhouse) | SQL driver for Clickhouse | 0.1.0, 0.1.1 | +| [xk6-sql-driver-sqlserver](https://github.com/grafana/xk6-sql-driver-sqlserver) | SQL driver for SQLite3 | 0.1.0, 0.1.1 | +| [xk6-sse](https://github.com/phymbert/xk6-sse) | Test with Server-Sent Events (SSE) | 0.1.10, 0.1.11 | -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. +## Require building a custom k6 binary - +### Your own extensions -Don't see what you need? Learn how you can [create a custom extension](https://grafana.com/docs/k6//extensions/create/). +If you have developed your own k6 extension or want to use an extension that's not available through automatic extension resolution, you'll need to build a custom k6 binary. This 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. + +Check out how to [build a custom k6 binary guide](https://grafana.com/docs/k6//extensions/run/#using-extensions-that-require-building-a-custom-k6-binary) to learn how to create your own k6 binary with custom extensions. + +### More ecosystem extensions + +{{< admonition type="caution" >}} + +The extensions in this category are not maintained nor audited by Grafana Labs. + +{{< /admonition >}} + +Many other extensions, maintained by members of the k6 ecosystem are available in [GitHub](https://github.com/topics/xk6). diff --git a/docs/sources/k6/next/extensions/run-extensions-using-binary-provisioning.md b/docs/sources/k6/next/extensions/run-extensions-using-binary-provisioning.md deleted file mode 100644 index f5c9dbe1f8..0000000000 --- a/docs/sources/k6/next/extensions/run-extensions-using-binary-provisioning.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -labels: - products: - - cloud -title: 'Run extensions using Binary Provisioning' -description: 'Learn how to run scripts that require extensions using Binary Provisioning.' -weight: 04 ---- - -# Run extensions using Binary Provisioning - -{{< admonition type="caution" >}} - -This is an experimental feature. Breaking changes might occur prior to the feature being made generally available. - -{{< /admonition >}} - -k6 supports [extensions](https://grafana.com/docs/k6//extensions/) as a way of extending k6 native functionality, and support a wider variety of use cases. - -Using k6 with extensions locally requires users to build a [custom k6 binary](https://grafana.com/docs/k6//extensions/#xk6-makes-custom-binaries) that includes the extension, which can then be used to run a test script. With the Binary Provisioning feature, Grafana Cloud k6 users can run tests with a [limited set of extensions](https://grafana.com/docs/grafana-cloud/testing/k6/author-run/use-k6-extensions/#supported-extensions-in-grafana-cloud), without having to manually build a k6 binary. - -The `archive` and `inspect` commands also support Binary Provisioning to allow creating archives for Grafana Cloud. - -## Before you begin - -To use Binary Provisioning, you'll need: - -- k6 v1.0 or greater [installed on your machine](https://grafana.com/docs/k6/latest/set-up/install-k6/). -- A [Grafana Cloud account](https://grafana.com/auth/sign-up/create-user). - -## Set the Binary Provsioning environment flag - -To enable Binary Provisioning, you must set the `K6_BINARY_PROVISIONING` environment variable to `true`: - -{{< code >}} - -```linux -export K6_BINARY_PROVISIONING=true -``` - -```mac -export K6_BINARY_PROVISIONING=true -``` - -```windows-powershell -$Env:K6_BINARY_PROVISIONING = "true" - -``` - -{{< /code >}} - -## Log in to Grafana Cloud - -To use Binary Provisioning, you must [authenticate to Grafana Cloud](https://grafana.com/docs/grafana-cloud/testing/k6/author-run/tokens-and-cli-authentication/#authenticate-with-the-login-command) using the `k6 cloud login` command: - -```bash -k6 cloud login --token -``` - -## Run a test - -After setting the `K6_BINARY_PROVISIONING` environment variable and logging in to Grafana Cloud, you can run a test using the `k6 cloud run` command: - -{{< code >}} - -```linux -k6 cloud run --local-execution script.js -``` - -```mac -k6 cloud run --local-execution --quiet script.js -``` - -```windows-powershell -k6.exe cloud run --local-execution --quiet script.js -``` - -```windows -k6.exe cloud run --local-execution --quiet script.js -``` - -{{< /code >}} - -As an example, you can save this script to your machine and run it in Grafana Cloud. It uses the [xk6-faker](https://github.com/grafana/xk6-faker) extension to generate a random first name. - - - -```javascript -import faker from 'k6/x/faker'; - -export default function () { - console.log(faker.person.firstName()); -} -``` - -You should see an output similar to the following: - -```sh -INFO[0000] The current k6 binary doesn't satisfy all dependencies, it is required to provision a custom binary. deps="k6/x/faker*" -INFO[0000] A new k6 binary has been provisioned with version(s): k6:v1.0.0 k6/x/faker:v0.4.3 -time="2025-04-24T12:59:24+02:00" level=info msg=Zelma source=console - - - TOTAL RESULTS - - EXECUTION - iteration_duration.....................: avg=759.06µs min=759.06µs med=759.06µs max=759.06µs p(90)=759.06µs p(95)=759.06µs - iterations.............................: 1 1061.414505/s - - NETWORK - data_received..........................: 0 B 0 B/s - data_sent..............................: 0 B 0 B/s -``` - -The output includes information about which dependencies were detected, and the version for the dependencies used to run the test. - -## Limitations - -- Only extensions supported in Grafana Cloud are supported. -- Output extensions are not supported. -- Running scripts from stdin is not supported. -- Only files with extensions `.js`, `.ts` or `.tar` can be used. Other extensions will not invoke the Binary Provisioning mechanism. diff --git a/docs/sources/k6/next/extensions/run/_index.md b/docs/sources/k6/next/extensions/run/_index.md new file mode 100644 index 0000000000..dc8de23863 --- /dev/null +++ b/docs/sources/k6/next/extensions/run/_index.md @@ -0,0 +1,77 @@ +--- +title: 'Run a test with extensions' +menuTitle: 'Run a test with extensions' +description: 'Run k6 with extensions to cover use cases not supported natively in the core.' +weight: 03 +--- + +# Run a test with extensions + +As explained in the [Explore extensions](https://grafana.com/docs/k6//extensions/explore) page, there are extensions that can be used directly in your test script, and others that require building a custom k6 binary. + +## Using automatic extension resolution + +It is as easy as importing them. Example with [xk6-faker](https://github.com/grafana/xk6-faker): + +```javascript +import faker from 'k6/x/faker'; + +export default function () { + console.log(faker.person.firstName()); +} +``` + +Then, you can run your script as usual, and k6 will automatically detect the extension and load it: + +```sh +k6 run script.js +``` + +{{< admonition type="note" >}} + +To use community extensions you must have `K6_ENABLE_COMMUNITY_EXTENSIONS` set to `true`. + + +```sh +K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js +``` + +{{< /admonition >}} + +### Limitations + +- Only works with Official and Community extensions. +- Output extensions are not supported. +- Running scripts from stdin is not supported. +- Only files with extensions `.js`, `.ts` or `.tar` can be used. + +### How to disable this feature + +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. +```bash +K6_AUTO_EXTENSION_RESOLUTION=false k6 run test.js +``` + +## Using extensions that require building a custom k6 binary + +To run other extensions (including ones you create), you need to build a custom k6 binary with [xk6](https://github.com/grafana/xk6/). + +You can do this locally with [Go](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-go/) or use the [xk6 Docker image](https://grafana.com/docs/k6//extensions/run/build-k6-binary-using-docker/). + +{{< code >}} + +```go-and-xk6 +xk6 build \ + --with github.com/grafana/xk6-sql@v0.0.1 \ + --with github.com/grafana/xk6-output-influxdb +``` + +```docker-in-linux +docker run --rm -u "$(id -u):$(id -g)" -v "${PWD}:/xk6" grafana/xk6 build \ + --with github.com/grafana/xk6-sql@v0.0.1 \ +``` + +{{< /code >}} + +
\ No newline at end of file diff --git a/docs/sources/k6/next/extensions/build-k6-binary-using-docker.md b/docs/sources/k6/next/extensions/run/build-k6-binary-using-docker.md similarity index 100% rename from docs/sources/k6/next/extensions/build-k6-binary-using-docker.md rename to docs/sources/k6/next/extensions/run/build-k6-binary-using-docker.md diff --git a/docs/sources/k6/next/extensions/build-k6-binary-using-go.md b/docs/sources/k6/next/extensions/run/build-k6-binary-using-go.md similarity index 100% rename from docs/sources/k6/next/extensions/build-k6-binary-using-go.md rename to docs/sources/k6/next/extensions/run/build-k6-binary-using-go.md diff --git a/scripts/extension-registry-changed b/scripts/extension-registry-changed deleted file mode 100755 index 78a1d46be3..0000000000 --- a/scripts/extension-registry-changed +++ /dev/null @@ -1,96 +0,0 @@ -#!/usr/bin/env bash - -# This script keeps the list of extensions up to date -# in the docs/sources/next/extensions/explore.md file. -# -# The script is run by the extension-registry.changed.yml -# workflow when the extension registry changes. -# -# The list of extensions is generated based on https://registry.k6.io/product/oss.json. -# -# In the docs/sources/next/extensions/explore.md file -# the content of the