Skip to content

Your first run

This walkthrough starts a local cluster with one control plane and three workers, builds the two images a run needs, and submits a first run. Everything happens inside your clone of the repository. Your default kubeconfig is never touched.

What you will see

A run parses its definition, resolves its two nodes, claims the cluster, starts its own Prometheus, runs the iperf2 test through Robot Framework, reads the result and evaluates the pass criteria against it. Robot's report comes back to your machine, and the run exits with its verdict. Only the CSV and JSONL result files are not built yet, and the run says so. How it works shows the phases.

1. Start a local cluster

The repository has its own test environment in test-env/. It installs pinned versions of its tools into the repository, not system-wide:

$ test-env/install-tools.sh .test-env/bin
$ export PATH="$PWD/.test-env/bin:$PATH"
$ test-env/test-env.sh up kind-kindnet
$ test-env/test-env.sh check
$ export KUBECONFIG=.test-env/kubeconfig

kind-kindnet is the fastest profile. Six others pair kind or k3d with Calico, Cilium or flannel, for when behaviour specific to one CNI matters:

Profile Tool CNI
kind-kindnet kind kindnet
kind-calico kind Calico
kind-cilium kind Cilium
kind-flannel kind flannel
k3d-flannel k3d flannel
k3d-calico k3d Calico
k3d-cilium k3d Cilium

check verifies that the cluster provides what a run needs.

2. Build the images

A source install has no default for the orchestrator image or the iperf2 test image, so build both. Your cluster cannot pull a local build from a registry, so they are loaded straight into the nodes. One command does all of it:

$ out=$(test-env/test-env.sh images) && eval "$out"

It builds orchestrator:dev and iperf2:dev from your checkout, loads both into every node, and sets DOKIMI_ORCHESTRATOR_IMAGE and DOKIMI_IPERF2_IMAGE to them. It also names the cluster test-env (DOKIMI_CLUSTER): every run needs a name for the cluster it runs on, and there is no default. Run it again after changing the code, to rebuild what the cluster runs.

Use it as written, not as eval "$(test-env/test-env.sh images)": if a build fails, that eval runs an empty string and succeeds, and the next run quietly uses the previous build.

Without the images, submit refuses before it creates anything, and says which image is missing. Without a cluster name, it refuses too. dokimi image shows every image a run would use. The Prometheus and node-exporter images are pulled from quay.io, so the cluster needs to reach it.

3. Create the namespaces and grant the run what it needs

$ kubectl apply -f deploy/rbac.yaml

4. Point the example at your nodes

The example names worker-01 and worker-02, which this cluster does not have. List the nodes it does have, and point a copy of the example at two of them:

$ test-env/test-env.sh nodes
dokimi-worker
dokimi-worker2
dokimi-worker3
$ sed -e 's/worker-01/dokimi-worker/' -e 's/worker-02/dokimi-worker2/' \
    examples/worker-01-to-worker-02-udp.yaml > kind-pair.yaml

5. Check the plan, then submit

$ uv run dokimi submit kind-pair.yaml --dry-run --kubeconfig .test-env/kubeconfig > /dev/null
$ uv run dokimi submit kind-pair.yaml --service-account dokimi

The first command resolves both nodes read-only and prints the plan. It creates nothing. The second submits the run and streams its log. In it you see the run:

  • claim the cluster, start its Prometheus and a node-exporter, and check that the Prometheus answers. It prints the kubectl port-forward command that reaches the Prometheus from your machine;
  • check the cluster with the test's own two pods: they are scheduled, pull their image, send a second of traffic and resolve a cluster name, and are removed again;
  • render the Robot suite and run it: the client and server pods are deployed on your two nodes, and iperf2 runs between them for the definition's duration, plus a warm-up pass;
  • read the result directly from the pods' exporters, and check that Prometheus holds it too;
  • evaluate each pass criterion against the result, and list it as pass or fail with the measured value;
  • say that the CSV and JSONL result files are not built yet, and record where every pod ran and how it ended;
  • remove the node-exporter, and the test pods if the test passed, and free the cluster.

It exits 0 if the test passed, 1 if a criterion didn't hold, and 2 if the test couldn't be validly measured. Robot's report lands in results/<run-id>/, under the directory you ran submit from: log.html, report.html, output.xml and the suite.robot that ran, plus measurement.json with what was measured and diagnostics.json with where everything ran. pairs/ holds each pair's validation.json, with what its criteria came to. Open log.html to see each step. Whether the test passes depends on your cluster: the example asks for 950 megabits per second without loss, which a cluster on one machine may not reach.

A run that didn't pass keeps its test pods, with their logs and events, for you to look at, and prints the command that removes them: uv run dokimi cleanup <run-id>.

To check the cluster without running a test, uv run dokimi preflight kind-pair.yaml --service-account dokimi runs only the checks, and exits 0 if the cluster is ready.

The Prometheus is kept after the run, passed or not; dokimi cleanup <run-id> --prometheus removes it. Using the CLI has the details.

Worth trying once, to see the errors a first run can hit: point the definition at dokimi-control-plane (it is tainted), kubectl cordon a worker, or leave off --service-account. Each fails with a message that names its fix.

What this cluster can and cannot tell you

All the nodes of this cluster share one machine's network stack. Traffic between them is limited by the host's CPU and memory, not by a network card or a real CNI datapath. It is the right place to check that dokimi orchestrates a run correctly. It says nothing about the network performance of real hardware.

6. Tear it down

$ test-env/test-env.sh down

down deletes the cluster, then fails if any container, volume or network labelled with it remains.