Documentation Grafana Cloud Testing and synthetics Synthetic Monitoring Create checks Manage k6 versions

Manage k6 versions

Grafana Cloud Synthetic Monitoring lets you select the k6 version that runs your checks, so you can stay on a stable major version while still receiving new features and bug fixes.

With k6 version channels, you can:

• Pin a check to a specific k6 major version.
• Receive minor and patch updates automatically without breaking existing scripts.
• Test new k6 major versions on selected checks before migrating them.

Before you begin

k6 version management applies only to k6 scripted and k6 browser checks.

About k6 version channels

A k6 version channel maps to a k6 major version. For example, the v1.x channel covers all v1 releases and the v2.x channel covers all v2 releases.

Minor and patch updates within a channel don’t include breaking changes, so they land automatically without breaking existing scripts. For example, a check on v1.x might run on k6 1.6.1 today and on 1.7.0 after the next k6 release, with no action required from you.

Breaking changes only happen when k6 releases a new major version, which introduces a new channel. Switching a check from one channel to another, for example from v1.x to v2.x, may require script changes. Test the script after switching to confirm it still runs as expected.

Channel support

Channel support follows the k6 versioning and stability guarantees:

• The latest major version is actively developed.
• The previous major version is supported, meaning it continues to receive bug fixes and security patches.
• Any earlier version is deprecated and doesn’t receive updates, bug fixes, or security patches.

For details on what happens to checks using a deprecated channel, refer to Deprecated channels. The selected channel also determines which probes can run the check; refer to Probe compatibility.

Select a channel for a check

1. On the left-side menu, select Testing & synthetics and then Synthetics.
2. Create a new check or open an existing one.
3. On the Script step, open the k6 version channel dropdown and select a channel.
4. Click Test to run the check once on the selected channel without saving, or click Save to persist the change. After saving, verify that recent executions complete successfully on the check dashboard.

The dropdown labels the latest stable channel as the default, for example, v1.x (default) or v2.x (default). If you don’t choose a channel, Synthetic Monitoring uses the default.

Changing the channel doesn’t run the check immediately. Test runs the check once without persisting the change; Save persists the new channel and uses it for all future executions. Selecting a channel can also change which probes are eligible to run the check, so review the Execution step before saving. For details, refer to Probe compatibility. If a channel is marked as deprecated, refer to Deprecated channels.

Probe compatibility

Each probe supports a specific set of k6 version channels. The channel you select on a check determines which probes are eligible to run it.

Public probes managed by Grafana support all non-deprecated channels, so compatibility issues mostly affect private probes.

You can view the channels each probe supports in several places:

• Execution step of the check form: each probe shows its current k6 version for the selected channel, and a tooltip lists all channels the probe supports.
• Probes list view.
• Probe detail view.

Before switching a check to a different channel, use the Probes list view to confirm that the probes you rely on support the new channel.

Probe states

On the Execution step, each probe is marked with one of three states for the selected channel:

• Known version (blue badge): the probe reports a specific k6 version for the channel, for example v1.6.1. The probe is selectable.
• Version unknown (orange badge): the probe is selectable, but compatibility with the selected channel can’t be guaranteed. This usually means the probe hasn’t connected to the Synthetic Monitoring API yet or hasn’t reported version information for the channel.
• Not supported (red badge): the probe doesn’t support the selected channel. The probe is disabled and can’t be selected.

When a probe is not supported

A Not supported badge means the private probe doesn’t have a k6 binary for the selected channel installed. This applies only to private probes; public probes managed by Grafana ship with all supported k6 binaries.

To resolve it, do one of the following:

• Select a different probe that supports the channel.
• Change the channel on the Script step to one the probe supports.
• Upgrade the private probe agent to a version that includes the required k6 binary. For details, refer to Set up private probes.

When a saved probe becomes incompatible

If you change the channel on an existing check and a previously saved probe no longer supports it, the probe stays selected but the form shows a validation error and prevents saving. To save the check, either clear the probe’s selection or change the channel back to one the probe supports.

Deprecated channels

Synthetic Monitoring decides when a channel becomes deprecated by setting a deprecation date on each channel. A deprecated channel stops receiving updates, bug fixes, and security patches. For details on which channels are supported at any given time, refer to Channel support.

When a channel is deprecated:

• Existing checks on the channel keep running. Synthetic Monitoring doesn’t automatically migrate or disable them.
• The channel remains visible in the k6 version channel dropdown for both new and existing checks.
• A warning appears in the UI when the channel is selected: “This k6 version channel was deprecated on [date]. Support for this version will end with the release of the next k6 major version. Please migrate your checks to a newer channel.”

When support ends

Support for a deprecated channel ends when the second major version after it ships. For example, k6 v1 support ends when k6 v3 is released. When that happens:

• Probes no longer have the deprecated k6 binary installed.
• Checks on the unsupported channel start reporting an error.

Migrate a check to a supported channel

Switching between major versions may require script changes, so test before saving:

1. Follow the steps in Select a channel for a check to choose a supported channel.
2. Click Test to confirm the script still runs on the new channel.
3. Click Save to persist the change.

View the k6 version used at runtime

When a check runs, Synthetic Monitoring resolves the selected channel to a specific k6 version based on what the running probe has installed. This is useful when debugging a failing check and you need to confirm exactly which patch version ran.

You can find the resolved version in the check execution logs. Each execution logs a line like:

text Copy

Check will be run with resolved k6 version k6version=1.6.1

To view the logs:

• Open the check dashboard and use the time point explorer to inspect logs for individual executions. For details, refer to Visualize check execution.
• Query the Loki logs for the check directly in Explore.

The resolved version can vary across probes for the same check if probes have different patch versions of k6 installed.