This tutorial walks you through deploying the Kates stack, running your first performance test, and understanding the results.
You need Docker, running, with about 16 GB of RAM available to it, plus Kind, kubectl, Helm and the kates CLI. Homebrew installs the last four on macOS and on Linux:
brew install kind kubectl helm bmscomp/tap/kates
kates versionFor Docker, use Docker Desktop, OrbStack or Colima on macOS, and Docker Engine on Linux. The kates formula also installs cosign, which kates deploy uses to check the signatures of the charts it pulls.
Without Homebrew on Linux, install Docker Engine, Kind, kubectl and Helm from their own install pages, then the CLI with the release installer, which checks the download against the release's checksums:
curl -fsSL https://raw.githubusercontent.com/bmscomp/kates/main/scripts/install-kates.sh | bashYou don't need a clone of the repository: a released kates installs the charts its release published. Building from source is for working on Kates itself; Building from source covers it.
kates deploy --topology isolatedWith no cluster reachable, kates deploy offers to create panda, a three-zone Kind cluster, and switches kubectl to it. Accept, and it then installs Strimzi, Kafka, monitoring, LitmusChaos and the Kates API. On a fresh machine this takes 5–10 minutes, most of it pulling images. When a cluster is already reachable, it deploys into kubectl's current context instead, so check kubectl config current-context first.
This installs the Kates API standalone, as one pod: the default, which every tutorial uses. To run it as a quorum that survives a lost node or an upgrade, kates deploy --kates-mode operator --kates-replicas 3 installs it under the Kates operator instead, behind the same Service and API key; Tutorial 16 walks through it.
--topology isolated puts each component in its own namespace (kafka, kates, monitoring, litmus), which the rest of this tutorial uses. --topology single puts the whole stack in one kates-stack namespace instead, which is fine for a scratch cluster but means every -n <namespace> below needs changing.
Tip
If kates deploy fails with image pull errors, check your internet connection and Docker disk space (docker system df). Kind needs at least 20GB of free disk space. After you fix the cause, run kates deploy again: it skips or upgrades what is already installed.
Verify everything is running:
kubectl get pods -n kafka
kubectl get pods -n katesAll pods should be Running. The Kates backend exposes a REST API that the CLI uses for all commands.
kates portskates ports forwards the Kates API to http://localhost:8080 and the other services to their ports, in the background. It writes a CLI context named ports, with the URL and the API key from the kates-api-key Secret, and makes it current.
kates healthExpected output:
Kates Health Check
─────────────────────
Engine ✅ UP
Kafka ✅ Connected (3 brokers)
API ✅ Responsive
Tip
If the health check fails, verify all pods are running with kubectl get pods -A and check the Kates backend logs with kubectl logs -n kates -l app.kubernetes.io/name=kates. The most common cause is the backend pod not being ready yet — wait 30 seconds and retry.
Explore the cluster:
# View cluster metadata
kates cluster
# List existing topics
kates cluster topics
# Full dashboard
kates dashboardLet's run a simple LOAD test — 100,000 messages with default settings. This sends messages to a Kafka topic at maximum speed and measures how fast your cluster can process them:
kates test create --type LOAD --records 100000 --waitThe --wait flag makes the CLI poll until the test completes. You'll see:
◉ Test created
ID a1b2c3d4-...
Type LOAD
Status RUNNING
⏳ Waiting for completion...
Progress: 25,000 / 100,000 (25%)
Progress: 50,000 / 100,000 (50%)
Progress: 75,000 / 100,000 (75%)
Progress: 100,000 / 100,000 (100%)
✅ Test completed
# List your tests
kates test list
# Get detailed results (replace with your actual ID)
kates test get <id>The output shows:
Test Run: a1b2c3d4
──────────────────
Type LOAD
Status DONE ✅
Created 2026-02-15 20:00:00
Results (1 phase)
┌─────────┬────────┬─────────┬────────────┬──────────┬──────────┐
│ Phase │ Status │ Records │ Throughput │ Avg Lat. │ P99 Lat. │
├─────────┼────────┼─────────┼────────────┼──────────┼──────────┤
│ default │ DONE │ 100,000 │ 45,230/s │ 4.12ms │ 12.34ms │
└─────────┴────────┴─────────┴────────────┴──────────┴──────────┘
kates report show <id>The report includes:
- Summary — aggregate throughput and latency
- Cluster snapshot — broker count, topic count at test time
- Broker metrics — per-broker load distribution
export writes to stdout, so redirect it to a file. The formats are csv,
junit, heatmap, heatmap-csv, md and html:
# CSV (spreadsheet analysis) — the default format
kates report export <id> --format csv > report.csv
# Heatmap (Grafana visualization)
kates report export <id> --format heatmap > heatmap.json
# JUnit (CI test reporting)
kates report export <id> --format junit > report.xmlFor the report as JSON, ask show for it instead: kates report show <id> -o json.
Let's add consumers to measure end-to-end behavior:
kates test create --type LOAD \
--records 100000 \
--producers 2 \
--consumers 2 \
--record-size 2048 \
--acks all \
--waitCompare your two test runs:
kates report diff <id1> <id2>This highlights differences in throughput, latency, and error rates between the runs.
- Tutorial 2: Running Every Test Type — learn all 8 test types
- Tutorial 3: Chaos Engineering — inject failures
- Tutorial 4: Data Integrity — verify zero data loss