Skip to content

Commit 4000caf

Browse files
pablochacinheitortsergentandrewslotin
authored
Add k6 binary provisioning preview (#1937)
* add k6 binary provisioning preview Signed-off-by: Pablo Chacin <[email protected]> * port changes to v1.0.x Signed-off-by: Pablo Chacin <[email protected]> * skip snip Signed-off-by: Pablo Chacin <[email protected]> * Apply suggestions from code review Co-authored-by: Heitor Tashiro Sergent <[email protected]> Co-authored-by: Andrey Slotin <[email protected]> * skip running example script Signed-off-by: Pablo Chacin <[email protected]> * remove unnecessary code directives Signed-off-by: Pablo Chacin <[email protected]> * Update binary provisioning to fit style guide --------- Signed-off-by: Pablo Chacin <[email protected]> Co-authored-by: Heitor Tashiro Sergent <[email protected]> Co-authored-by: Andrey Slotin <[email protected]>
1 parent 22fc0ed commit 4000caf

File tree

2 files changed

+244
-0
lines changed

2 files changed

+244
-0
lines changed

‎docs/sources/k6/next/extensions/run-extensions-using-binary-provisioning.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
labels:
3+
products:
4+
- cloud
5+
title: 'Run extensions using Binary Provisioning'
6+
description: 'Learn how to run scripts that require extensions using Binary Provisioning.'
7+
weight: 04
8+
---
9+
10+
# Run extensions using Binary Provisioning
11+
12+
{{< admonition type="caution" >}}
13+
14+
This is an experimental feature. Breaking changes might occur prior to the feature being made generally available.
15+
16+
{{< /admonition >}}
17+
18+
k6 supports [extensions](https://grafana.com/docs/k6/<K6_VERSION>/extensions/) as a way of extending k6 native functionality, and support a wider variety of use cases.
19+
20+
Using k6 with extensions locally requires users to build a [custom k6 binary](https://grafana.com/docs/k6/<K6_VERSION>/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.
21+
22+
The `archive` and `inspect` commands also support Binary Provisioning to allow creating archives for Grafana Cloud.
23+
24+
## Before you begin
25+
26+
To use Binary Provisioning, you'll need:
27+
28+
- k6 v1.0 or greater [installed on your machine](https://grafana.com/docs/k6/latest/set-up/install-k6/).
29+
- A [Grafana Cloud account](https://grafana.com/auth/sign-up/create-user).
30+
31+
## Set the Binary Provsioning environment flag
32+
33+
To enable Binary Provisioning, you must set the `K6_BINARY_PROVISIONING` environment variable to `true`:
34+
35+
{{< code >}}
36+
37+
```linux
38+
export K6_BINARY_PROVISIONING=true
39+
```
40+
41+
```mac
42+
export K6_BINARY_PROVISIONING=true
43+
```
44+
45+
```windows-powershell
46+
$Env:K6_BINARY_PROVISIONING = "true"
47+
48+
```
49+
50+
{{< /code >}}
51+
52+
## Log in to Grafana Cloud
53+
54+
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:
55+
56+
```bash
57+
k6 cloud login --token <API_TOKEN>
58+
```
59+
60+
## Run a test
61+
62+
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:
63+
64+
{{< code >}}
65+
66+
```linux
67+
k6 cloud run --local-execution script.js
68+
```
69+
70+
```mac
71+
k6 cloud run --local-execution --quiet script.js
72+
```
73+
74+
```windows-powershell
75+
k6.exe cloud run --local-execution --quiet script.js
76+
```
77+
78+
```windows
79+
k6.exe cloud run --local-execution --quiet script.js
80+
```
81+
82+
{{< /code >}}
83+
84+
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.
85+
86+
<!-- md-k6:skip -->
87+
88+
```javascript
89+
import faker from 'k6/x/faker';
90+
91+
export default function () {
92+
console.log(faker.person.firstName());
93+
}
94+
```
95+
96+
You should see an output similar to the following:
97+
98+
```sh
99+
INFO[0000] The current k6 binary doesn't satisfy all dependencies, it is required to provision a custom binary. deps="k6/x/faker*"
100+
INFO[0000] A new k6 binary has been provisioned with version(s): k6:v1.0.0 k6/x/faker:v0.4.3
101+
time="2025-04-24T12:59:24+02:00" level=info msg=Zelma source=console
102+
103+
104+
TOTAL RESULTS
105+
106+
EXECUTION
107+
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
108+
iterations.............................: 1 1061.414505/s
109+
110+
NETWORK
111+
data_received..........................: 0 B 0 B/s
112+
data_sent..............................: 0 B 0 B/s
113+
```
114+
115+
The output includes information about which dependencies were detected, and the version for the dependencies used to run the test.
116+
117+
## Limitations
118+
119+
- Only extensions supported in Grafana Cloud are supported.
120+
- Output extensions are not supported.
121+
- Running scripts from stdin is not supported.
122+
- Only files with extensions `.js`, `.ts` or `.tar` can be used. Other extensions will not invoke the Binary Provisioning mechanism.

‎docs/sources/k6/v1.0.x/extensions/run-extensions-using-binary-provisioning.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
labels:
3+
products:
4+
- cloud
5+
title: 'Run extensions using Binary Provisioning'
6+
description: 'Learn how to run scripts that require extensions using Binary Provisioning.'
7+
weight: 04
8+
---
9+
10+
# Run extensions using Binary Provisioning
11+
12+
{{< admonition type="caution" >}}
13+
14+
This is an experimental feature. Breaking changes might occur prior to the feature being made generally available.
15+
16+
{{< /admonition >}}
17+
18+
k6 supports [extensions](https://grafana.com/docs/k6/<K6_VERSION>/extensions/) as a way of extending k6 native functionality, and support a wider variety of use cases.
19+
20+
Using k6 with extensions locally requires users to build a [custom k6 binary](https://grafana.com/docs/k6/<K6_VERSION>/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.
21+
22+
The `archive` and `inspect` commands also support Binary Provisioning to allow creating archives for Grafana Cloud.
23+
24+
## Before you begin
25+
26+
To use Binary Provisioning, you'll need:
27+
28+
- k6 v1.0 or greater [installed on your machine](https://grafana.com/docs/k6/latest/set-up/install-k6/).
29+
- A [Grafana Cloud account](https://grafana.com/auth/sign-up/create-user).
30+
31+
## Set the Binary Provsioning environment flag
32+
33+
To enable Binary Provisioning, you must set the `K6_BINARY_PROVISIONING` environment variable to `true`:
34+
35+
{{< code >}}
36+
37+
```linux
38+
export K6_BINARY_PROVISIONING=true
39+
```
40+
41+
```mac
42+
export K6_BINARY_PROVISIONING=true
43+
```
44+
45+
```windows-powershell
46+
$Env:K6_BINARY_PROVISIONING = "true"
47+
48+
```
49+
50+
{{< /code >}}
51+
52+
## Log in to Grafana Cloud
53+
54+
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:
55+
56+
```bash
57+
k6 cloud login --token <API_TOKEN>
58+
```
59+
60+
## Run a test
61+
62+
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:
63+
64+
{{< code >}}
65+
66+
```linux
67+
k6 cloud run --local-execution script.js
68+
```
69+
70+
```mac
71+
k6 cloud run --local-execution --quiet script.js
72+
```
73+
74+
```windows-powershell
75+
k6.exe cloud run --local-execution --quiet script.js
76+
```
77+
78+
```windows
79+
k6.exe cloud run --local-execution --quiet script.js
80+
```
81+
82+
{{< /code >}}
83+
84+
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.
85+
86+
<!-- md-k6:skip -->
87+
88+
```javascript
89+
import faker from 'k6/x/faker';
90+
91+
export default function () {
92+
console.log(faker.person.firstName());
93+
}
94+
```
95+
96+
You should see an output similar to the following:
97+
98+
```sh
99+
INFO[0000] The current k6 binary doesn't satisfy all dependencies, it is required to provision a custom binary. deps="k6/x/faker*"
100+
INFO[0000] A new k6 binary has been provisioned with version(s): k6:v1.0.0 k6/x/faker:v0.4.3
101+
time="2025-04-24T12:59:24+02:00" level=info msg=Zelma source=console
102+
103+
104+
TOTAL RESULTS
105+
106+
EXECUTION
107+
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
108+
iterations.............................: 1 1061.414505/s
109+
110+
NETWORK
111+
data_received..........................: 0 B 0 B/s
112+
data_sent..............................: 0 B 0 B/s
113+
```
114+
115+
The output includes information about which dependencies were detected, and the version for the dependencies used to run the test.
116+
117+
## Limitations
118+
119+
- Only extensions supported in Grafana Cloud are supported.
120+
- Output extensions are not supported.
121+
- Running scripts from stdin is not supported.
122+
- Only files with extensions `.js`, `.ts` or `.tar` can be used. Other extensions will not invoke the Binary Provisioning mechanism.

0 commit comments

Comments
 (0)