01-getting-started.md

Tutorial 1: Getting Started with Kates

This tutorial walks you through deploying the Kates stack, running your first performance test, and understanding the results.

Step 1: Deploy the Infrastructure

If you haven't already deployed the cluster, run:

make all

This creates the Kind cluster, pulls all container images, and deploys Kafka, monitoring, and LitmusChaos. This is a one-time setup step — it takes 5–10 minutes on a fresh machine.

make all prompts for a topology before it does anything. Choose 2, isolated namespaces — the rest of this tutorial uses the namespaces that choice creates (kafka, kates, monitoring, litmus). Option 1 puts the whole stack in a single kates-stack namespace instead, which is fine for a scratch cluster but means every -n <namespace> below needs changing.

Tip

If make all 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.

Verify everything is running:

make status

Expected output: all pods across kafka, monitoring, and litmus namespaces should be Running.

Step 2: Deploy Kates

make kates

This builds the Kates Quarkus application, creates a Docker image, loads it into Kind, and deploys it to the kates namespace. The backend exposes a REST API on port 30083 that the CLI uses for all commands.

Verify:

kubectl get pods -n kates

You should see the Kates pod running.

Step 3: Install and Configure the CLI

# Build and install
make cli-install

# Create a context
kates ctx set local --url http://localhost:30083
kates ctx use local

Step 4: Verify Connectivity

kates health

Expected 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 dashboard

Step 5: Run Your First Test

Let'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 --wait

The --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

Step 6: View the Results

# 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  │
  └─────────┴────────┴─────────┴────────────┴──────────┴──────────┘

Step 7: View the Report

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

Step 8: Export the Data

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.xml

For the report as JSON, ask show for it instead: kates report show <id> -o json.

Step 9: Run a Test with Consumers

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 \
  --wait

Step 10: Compare Results

Compare your two test runs:

kates report diff <id1> <id2>

This highlights differences in throughput, latency, and error rates between the runs.

What's Next?

• 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