Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 36 ยท CI and Cloud

Grafana Cloud k6: Cloud and Local Execution

Understand Grafana Cloud k6: cloud execution versus local execution with cloud results, load zones and distribution, run comparison, scheduling, cost in VU hours and when open source is enough.

Everything so far works with the open-source k6 binary. Grafana Cloud k6 is the hosted product around it: it runs your scripts on managed load generators, stores every test run, draws the graphs, compares runs and aggregates results across machines. The scripts do not change. Whether you need it depends on how much infrastructure and history you want to manage yourself.

Honesty note. Grafana Cloud is an external paid service (with a free tier whose limits change), so none of it runs here. Commands and options are read-only and were written from the product's documented behaviour; check the current documentation for exact flags, limits and pricing before relying on them. The runnable blocks are Node stand-ins for the arithmetic you do when planning a cloud test.

Two ways to use the cloud

Mode Where the load is generated Where results go When to choose it
Cloud execution Grafana's load generators in the regions you pick Grafana Cloud Public targets, large tests, multi-region traffic
Local execution, cloud results Your machine or CI runner Grafana Cloud Targets inside your network, plus hosted dashboards

Both start with authentication. You create an account and a token, then log in once:

Terminal
k6 cloud login --token "$K6_CLOUD_TOKEN"

In CI, set the token (and the project) through environment variables or secrets instead of an interactive login.

Cloud execution

Terminal
k6 cloud run script.js

k6 uploads the script (and the files it opens), the cloud allocates generators, runs the test and streams results to the web app. Your terminal shows progress and can follow the run to completion; the exit code still reflects thresholds, so CI gating works the same way as in k6 in CI pipelines.

Cloud-specific settings live under options.cloud:

JavaScript
export const options = {
  cloud: {
    projectID: 1234567,
    name: 'Checkout load: build 482',
    distribution: {
      ashburn: { loadZone: 'amazon:us:ashburn', percent: 50 },
      dublin: { loadZone: 'amazon:ie:dublin', percent: 30 },
      tokyo: { loadZone: 'amazon:jp:tokyo', percent: 20 },
    },
  },
  scenarios: { /* ... */ },
};

distribution splits the load across load zones, so you can see how latency differs for users in the US, Europe and Asia. The percentages must add up to 100.

Local execution with cloud results

Terminal
k6 run -o cloud script.js

(or, in newer versions, the cloud command's local-execution option). The generator is yours, but samples are streamed to the cloud. This is the right choice when the system under test is not reachable from the internet. For that case Grafana also offers private load zones: runners you host in your own network (for example in Kubernetes with the operator from the previous lesson) that the cloud service orchestrates.

What the cloud adds

  • Aggregated results. Thresholds and percentiles are computed over all generators, which solves the distributed-test trap of per-instance evaluation.
  • Test run history and comparison. You can compare a run with a previous one, mark a baseline and see regressions at a glance. This is the feature teams without their own time-series database miss most.
  • Correlation with system metrics. In Grafana, you can overlay k6 metrics with the dashboards of your application (CPU, database latency, queue depth) on one time axis, which turns "p(95) went up" into "the database connection pool was exhausted at 10:32".
  • Scheduling and projects. Run tests on a schedule and organize them per team.
  • Load zones across the world without renting machines.
  • Insights. Automatic hints, for example a high rate of failed requests or a slow-start pattern.

What the cloud does not change

It does not make a bad test good. If your workload model is unrealistic, or the test data collides, you simply get a well-drawn graph of the wrong thing. It also does not replace observability of your own service: k6 sees what a client sees; your APM and logs explain why.

Cost: think in VU hours

Cloud tests are typically billed in virtual user hours (VUh): virtual users multiplied by hours they were active. A test with 500 VUs for 30 minutes is about 250 VUh. Browser VUs usually count for more than protocol VUs. Always check the current pricing page and your plan's limits, and:

  • Use the local execution with cloud results mode for small tests that fit on your own runner.
  • Keep smoke tests local and send only the heavy tests to the cloud.
  • Set a maximum VU count and duration in scripts to avoid accidental expensive runs.
Node.js Stand-in: planning a cloud test (zones and VU hours)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Choosing between open source and cloud

Situation Suggested choice
Learning, one-off checks, a pipeline smoke test Open-source k6 locally
Regular tests, one team, you already run Prometheus and Grafana k6 + --out to your stack
Large tests, many regions, no desire to manage generators Cloud execution
Internal targets but you want hosted history Local execution with cloud results, or private load zones
Strict data residency rules Self-hosted stack or private load zones; read the provider's data policies

There is no lock-in at the script level: a script written for open-source k6 runs in the cloud and vice versa, apart from the optional cloud options block.

Node.js Stand-in: run comparison against a baseline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Your staging system is only reachable inside a private network. Which option fits best?

    The generators must be able to reach the target, so run them inside your network and still send results to the cloud.
  2. 2. What does the distribution option in options.cloud control?

    distribution assigns percentages of the load to regions (load zones); the percentages must total 100.
  3. 3. A cloud test runs 200 VUs for 3 hours. About how many VU hours is that?

    VU hours = VUs x hours = 200 x 3 = 600.
  4. 4. Which problem of distributed open-source runs does the cloud solve out of the box?

    Results from all generators are merged centrally, so thresholds are evaluated on the whole test.

Summary

  • Cloud execution runs the load on hosted generators; local execution with cloud results streams your own run's data.
  • Load zones and distribution simulate traffic from several regions.
  • The big wins are aggregated results, run history and comparison, and correlation with system metrics.
  • Costs follow VU hours; keep small tests local and verify current limits and prices.

Next: Test Design and Workload Models