Installation¶
The CLI runs on your machine or in CI. The orchestrator runs inside the cluster as a one-shot Job, and you never install that: the CLI submits it.
What you need¶
| Python | 3.14 or newer. uv fetches it if your system has none |
uv |
0.12.18 or newer. This is enforced, because 0.12.18 fixes a path-traversal weakness during wheel installation |
| Kubernetes | 1.35 or newer, with credentials that can create Jobs and ConfigMaps in the run's namespace, and, once, an administrator to apply deploy/rbac.yaml, which creates that namespace and the dokimi lock namespace |
| A container registry | only if your cluster cannot reach ghcr.io, or quay.io for Prometheus and node-exporter |
Robot Framework is not required on your machine. It runs inside the cluster.
Supported platforms¶
| Platform | Status |
|---|---|
| macOS, Apple silicon | supported and tested |
| Linux, x86_64 | supported and tested |
| macOS, Intel · Linux, arm64 | supported, not yet tested |
| Windows, through WSL2 | supported and tested. WSL2 takes the Linux path |
| Windows, natively | not supported |
On WSL2, clone the repository inside the Linux filesystem (~/…), not under /mnt/c/…, where
every file shows as mode 0777 and file access is much slower. It was tested with the Docker
engine installed in the Linux distribution; Docker Desktop's WSL2 integration is expected to work,
but was not tested.
Install uv¶
$ curl -LsSf https://astral.sh/uv/install.sh | sh # macOS, Linux
$ brew install uv # or with Homebrew
Install dokimi from source¶
dokimi is not on PyPI yet. Install it from the repository:
$ git clone https://github.com/dokimi-io/dokimi.git
$ cd dokimi
$ uv sync --locked
$ uv run dokimi --version
To get a dokimi command on your PATH instead of one behind uv run:
Check the installation¶
$ dokimi validate examples/worker-01-to-worker-02-udp.yaml
examples/worker-01-to-worker-02-udp.yaml is valid.
name worker-01-to-worker-02-udp
pair worker-01 -> worker-02
test iperf2 over udp
...
validate contacts nothing, so it works before you have a cluster.
Cluster credentials¶
The CLI picks cluster credentials in this order:
--kubeconfigand--context, if either is given, and then only those;- otherwise, in-cluster service-account credentials, when it runs inside a pod;
- otherwise,
$KUBECONFIG, or~/.kube/config.
The second entry is why the same command works unchanged in a CI job that runs inside the cluster it tests.
Once per cluster: deploy/rbac.yaml¶
A run never creates a namespace, so submitting needs permissions only inside the run's namespace. The Job a run submits authenticates as its own service account, not as you, and three of the things it does are cluster-wide:
- it reads the cluster's nodes, to plan;
- it lists ConfigMaps in every namespace, to check that no other run is active, and takes a
Leasein thedokiminamespace while it claims the cluster. Kubernetes cannot restrict alistby label, so this grant can read every ConfigMap in the cluster, including its data. That is the price of one run at a time per cluster; - it lists Services in every namespace, to find a node-exporter or kube-state-metrics the cluster already runs, so that its Prometheus scrapes those, and the run does not deploy a second node-exporter.
The run's Prometheus runs as a second service account, dokimi-prometheus, which can read
pods, Services and endpoint slices in every namespace, to discover what it scrapes. It is
read-only.
So an administrator applies this once per cluster:
It creates the dokimi-iperf2 namespace for runs, the dokimi namespace for the run-start lock,
a dokimi service account, and the grants it needs, each commented with the phase that needs
it. Runs then pass --service-account dokimi.
Inside dokimi-iperf2, the grants let the Job:
- write its claim onto its own owner ConfigMap and read its own Job;
- create the ConfigMap, Deployment and Service of its Prometheus. No grant lets the Job delete them, because they are kept after the run;
- create, read, list and delete DaemonSets, for the node-exporter it deploys when the cluster has none and removes when it ends;
- create, read, list and delete Pods, for the client and server pod each test runs in, removed
when the run ends, unless a run that didn't pass keeps them. There is no grant for
pods/exec: a test is started over the network, not by running a command inside a pod.
The Job deletes nothing else. A run's owner, definition and Job go after the run, removed by
whoever fetched its reports, or by dokimi cleanup, with their own credentials.
What you need yourself¶
You, or the CI job that submits, need only namespaced permissions in the run's namespace:
| Command | Needs |
|---|---|
submit, preflight |
create on Jobs and ConfigMaps; get on Pods and their log, and list on Jobs and Pods, to follow the run; and, once the reports are fetched, get and delete on ConfigMaps and list and delete on Jobs, to remove the run |
attach |
the same, without create; get on ConfigMaps also finds the run's results directory |
cleanup |
get on ConfigMaps, and list and delete on ConfigMaps, Pods, Services, ServiceAccounts, Jobs, Deployments, DaemonSets and StatefulSets |
A missing delete after a fetch is only a warning: the cluster removes the Job an hour after the
run ended, and dokimi cleanup removes the rest.
Network paths a test needs¶
If a NetworkPolicy applies in dokimi-iperf2, it has to allow three paths:
- from the Job to each client pod, on 5101/TCP. That is how a test is started: the Job connects and sends the server's address;
- from the client pod to the server pod, on 5001, over the test's protocol, UDP or TCP;
- from the Job to each test pod's exporter, on 9101/TCP. That is how the result is read. A
cluster that blocks it fails every test as
metrics_missing.
Test traffic uses the pod network and IPv4, so a pod network without IPv4 cannot run a test. The
run checks the first two paths, the address family and the cluster's DNS before any test, with
dokimi preflight's checks. The third it cannot check in advance.
The run's own Prometheus adds three more: from the Job to the Prometheus on 9090/TCP, from the Prometheus to each test pod's exporter on 9101/TCP, and from the Prometheus to the node-exporter on 9137/TCP on each node's address, if the run deployed one.
The images a run uses¶
A run uses four images, called components:
| Component | What it is | Default in a source install |
|---|---|---|
orchestrator |
the run's own Job | none |
iperf2 |
the test workload, client and server | none |
prometheus |
the run's Prometheus | quay.io/prometheus/prometheus, pinned by digest |
node-exporter |
the node-exporter a run deploys when the cluster has none | quay.io/prometheus/node-exporter, pinned by digest |
Once releases exist, the CLI will ship with the digests of the orchestrator and iperf2
images built from its own commit. There is no release yet, so a source install has no default
for those two, and submit refuses, before it creates anything, instead of guessing:
$ dokimi submit test.yaml
dokimi: this is a development build with no published orchestrator image, so there is no
default to run. Choose one with --image orchestrator=<reference> or DOKIMI_ORCHESTRATOR_IMAGE
Each component is chosen the same way, highest first:
| Source | How | Scope |
|---|---|---|
| Run override | --image <component>=<reference>, repeatable |
one run |
| Installation override | DOKIMI_<COMPONENT>_IMAGE, for example DOKIMI_IPERF2_IMAGE or DOKIMI_NODE_EXPORTER_IMAGE, on the machine that submits |
one installation |
| Release default | built into a released CLI, by digest | the released build |
--orchestrator-image and DOKIMI_IMAGE are the earlier names for the orchestrator, and still
work. Images are chosen when you submit, never in the test definition: the same test runs
unchanged in every cluster, while each site can pull from its own mirror. submit writes every
image into the Job, so --dry-run shows exactly what will run, and dokimi image lists every
component and where its reference came from.
Build the orchestrator and iperf2 images yourself and point dokimi at them.
Your first run shows how.
The cluster's name¶
Every result is labelled with the cluster it was measured on, so that history from two clusters is never mixed up. dokimi doesn't guess that name, not from the kubeconfig context and not from the cluster. You give it, and there is no default:
| Source | How | Scope |
|---|---|---|
| Run override | --cluster lab-fra-1, on submit or preflight |
one run |
| Installation override | DOKIMI_CLUSTER=lab-fra-1, on the machine that submits |
one installation |
Without either, submit refuses before it creates anything, a dry run included. The name is a
DNS label: lowercase letters, digits and hyphens, starting and ending with a letter or digit, at
most 63 characters. Anything else is refused rather than rewritten. submit writes the name into
the Job, and --dry-run shows it.
It only names the cluster. The cluster credentials choose which cluster
a run goes to, so --cluster prod with a staging context runs on staging, labelled prod. Pick
one name per cluster and keep it.