Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ Performance tests work against any Kafka cluster the Kates API can reach; fault
- **Security audit.** `kates security audit` grades broker configuration A–F. Related commands map the checks to CIS, SOC 2 and PCI DSS, save a baseline and report drift from it.
- **CI gates.** `kates gate --min-grade B` runs a load test and exits non-zero below the performance grade, `kates test apply -f <scenario> --wait` fails when a scenario violates its SLA gates, and `kates security gate` does the same for the security grade. Finished tests can notify webhooks (`kates webhook add`).
- **A multi-zone lab on one machine.** A three-node Kind cluster (`panda`) whose nodes (`alpha`, `sigma`, `gamma`) sit in separate zones. On it, `kates deploy` gives each zone its own StorageClass and broker pool and turns on rack awareness, so a full zone failure can be rehearsed locally.
- **A Kates API that survives a lost node.** The default install runs the Kates API standalone, as one pod, and keeps working as it always has. `kates deploy --kates-mode operator --kates-replicas 3` runs it under the Kates operator instead: a quorum of three or five behind the same Service and key, whose leader is replaced within seconds, and which drains live runs before an upgrade. See [Running Kates Under the Kates Operator](docs/book/kates-operator.md).
- **Metrics and dashboards.** The Kates API exposes Prometheus metrics, the `monitoring` chart adds twelve Grafana dashboards for Kafka, Kates and chaos runs, and the charts ship Prometheus alert rules. The Kates API also exports OTLP traces, though the default install has no Jaeger to receive them; [Observability](docs/book/09-observability.md) covers the dashboards, the alerts and tracing.

## Why Kates
Expand Down Expand Up @@ -147,7 +148,9 @@ With the default isolated topology:
| Kafka UI | `kafka-ui` | `kafka` |
| LitmusChaos | `chaos` | `litmus` |

Kafka Connect, MirrorMaker 2, Kyverno and the secret manager are opt-in (`--with-kafka-connect`, `--with-mirror-maker2`, `--with-kyverno`, `--with-secret-manager`). `--topology single` puts everything except the operators in one namespace, `kates-stack`. After a failure, fix the cause and run `kates deploy` again: it skips or upgrades the components already installed.
Kafka Connect, MirrorMaker 2, Kyverno and the secret manager are opt-in (`--with-kafka-connect`, `--with-mirror-maker2`, `--with-kyverno`, `--with-secret-manager`). `--topology single` puts everything except the operators in one namespace, `kates-stack`.

The table shows the default, standalone mode: the `kates` chart runs the Kates API as one pod, and every install made before the operator mode keeps working unchanged. With `--kates-mode operator --kates-replicas 3`, deploy installs the Kates operator (release `kates-operator` in `kates-operator`) and a PostgreSQL for Kates (`kates-db`) instead, and the operator runs the Kates API as a quorum of three. Its leader takes the writes, a new one is elected within seconds when it dies, a member whose node is gone is rebuilt elsewhere, and `mode: Drain` lets an upgrade wait for live runs. The Service `kates` and the Secret `kates-api-key` are the same in both modes, so every command below works with either. [Running Kates Under the Kates Operator](docs/book/kates-operator.md) explains the mode, and [Tutorial 16](docs/tutorials/16-running-kates-under-the-operator.md) walks through it. After a failure, fix the cause and run `kates deploy` again: it skips or upgrades the components already installed.

### Reach the services

Expand Down Expand Up @@ -260,11 +263,12 @@ The CLI and its full-screen views talk to the backend over REST. The backend als
| Where | What |
|:--|:--|
| [The book](https://bmscomp.github.io/kates/) ([source](docs/book/README.md)) | Concepts, the CLI, the REST and gRPC APIs, deployment, security, upgrades and troubleshooting |
| [Tutorials](docs/tutorials/README.md) | Step-by-step labs: a first test, every test type, chaos, CI integration, Kafka Connect, MirrorMaker 2 migrations, dashboards |
| [Tutorials](docs/tutorials/README.md) | Step-by-step labs: a first test, every test type, chaos, CI integration, Kafka Connect, MirrorMaker 2 migrations, dashboards, the Kates operator |
| [CLI reference](docs/book/10-cli-reference.md) | Commands, flags and contexts |
| [REST API](docs/book/11-api-reference.md) · [gRPC API](docs/book/16-grpc-api.md) | Endpoints, authentication, exports |
| [Chaos in practice](docs/book/07-chaos-practice.md) | Disruption types, providers, playbooks, guardrails and grading |
| [Deployment](docs/book/12-deployment.md) · [Installing Kafka with Helm](docs/book/20-installation-guide.md) | Topologies, sizing, cloud overlays, chart-by-chart installs |
| [Kates operator](docs/book/kates-operator.md) · [its chart](operator/chart/README.md) | The Kates API as a quorum: deploy, conditions, failover, drained upgrades; standalone stays the default |
| [Troubleshooting Index](docs/book/appendix-b-troubleshooting.md) | Symptoms mapped to causes and chapters |
| [Version matrix](docs/book/appendix-d-versions.md) | Every pinned version (Kafka, Strimzi, Quarkus, Java, Go, charts), generated and checked in CI |
| [Local development](docs/local-development.md) | Makefile targets, image management, working behind a proxy |
Expand Down
4 changes: 2 additions & 2 deletions docs/book/12-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ The old PersistentVolumeClaim stays until you delete it.
kates deploy --kates-mode operator --kates-replicas 3
```

Either way the Service is `kates` in the Kates namespace, and the API key is in Secret `kates-api-key`, so `kates ports`, `kates health` and the rest work the same. Deploy refuses to install one mode over the other: uninstall first (`kates clean`), or keep the mode you have. `kates clean` removes the `Kates` resource while the operator still runs, then the operator. The operator doesn't yet support the `INTEGRATION_CDC` test.
[Running Kates Under the Kates Operator](kates-operator.md) explains the operator mode in full: the quorum, its conditions, draining before an upgrade and what stays the same in the standalone mode. Either way the Service is `kates` in the Kates namespace, and the API key is in Secret `kates-api-key`, so `kates ports`, `kates health` and the rest work the same. Deploy refuses to install one mode over the other: uninstall first (`kates clean`), or keep the mode you have. `kates clean` removes the `Kates` resource while the operator still runs, then the operator. The operator doesn't yet support the `INTEGRATION_CDC` test.

For Kafka broker storage, always use persistent volumes — even in development. Kafka's log retention depends on data being durable, and losing broker data mid-test invalidates results.

Expand Down Expand Up @@ -1382,4 +1382,4 @@ This deletes the Kind cluster and all associated resources.
- `make all` is `kates deploy` with a topology prompt; the per-component targets build the same stack piece by piece.
- The JVM image measures with a low-pause collector; the native image starts fast but pauses, so it suits CI, not measurement.

Your stack is running, so check that it is the cluster you meant to build: [Compliance Checks](compliance.md) writes that architecture down as a file and holds `krafter` to it.
Your stack is running with the Kates API as one standalone pod. If a lost node or an upgrade must not take it down, [Running Kates Under the Kates Operator](kates-operator.md) runs it as a quorum behind the same Service.
2 changes: 2 additions & 0 deletions docs/book/18-upgrade-playbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,8 @@ The `kates` chart installs the Kates API, the service in the cluster that runs y

Use this procedure to move the Kates API to a new release, after Kafka. It needs the published chart of that release, or on Kind the repository's `charts/kates`, and rights to upgrade the `kates` release in the `kates` namespace. When the new pods don't become ready, read their log with `kubectl logs deployment/kates -n kates`, and roll back with Step 4.

This procedure is for the standalone mode, the default. Under the Kates operator there is no `kates` release to upgrade: you change the `Kates` resource's version, and under `mode: Drain` no live run is lost, as [Upgrading Without Losing a Run](kates-operator.md#upgrading-without-losing-a-run) shows.

### Step 1 — Find the Chart for the New Version

A chart version and the Kates API version it ships differ, so read the pair from the chart itself. The [Version & Compatibility Matrix](appendix-d-versions.md) lists the pair for this release:
Expand Down
1 change: 1 addition & 0 deletions docs/book/CONCEPTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ Part V is home to the platform around the cluster: the operator, the charts, sec
| Operator, custom resource, CRD and reconciliation | [How the Operator Works](deploying-strimzi-operator.md#how-the-operator-works), in [Deploying the Strimzi Operator](deploying-strimzi-operator.md) | The Strimzi Cluster Operator watches custom resources such as `Kafka` and `KafkaNodePool` and changes the cluster's pods, Secrets and other objects until they match, so while it's down, changes to those resources wait. | `gl-operator`; also `gl-custom-resource`, `gl-crd`, `gl-reconciliation` |
| Installing and upgrading the operator | [Upgrading the Operator](deploying-strimzi-operator.md#upgrading-the-operator), in [Deploying the Strimzi Operator](deploying-strimzi-operator.md) | The Strimzi operator is its own Helm release, `strimzi-operator` in the `strimzi-operator` namespace, installed and upgraded separately from the Kafka clusters it manages. | `gl-strimzi` |
| Which Kates image runs where, and whose GC shows in P99 | planned: JVM or Native Image (Phase C), in [Deployment Guide](12-deployment.md) | `kates deploy` runs the Kates API as a native image on every cluster, which uses GraalVM's Serial GC, and a plain `helm install` the JVM image with generational ZGC, so the P99 and Max of a run `kates deploy` set up include Serial GC pauses. | `gl-graalvm-native-image`; also `gl-virtual-thread` |
| The Kates operator, its quorum and the standalone mode | [Two Modes, One API](kates-operator.md#two-modes-one-api), in [Running Kates Under the Kates Operator](kates-operator.md) | `kates deploy --kates-mode operator` runs the Kates API from a `Kates` resource, as one member or a quorum of three or five whose leader takes the writes behind the same `kates` Service, while the standalone `kates` chart stays the default and unchanged. | `gl-kates-operator` |
| Single versus isolated namespace topology | [Single-Namespace vs Multi-Namespace](12-deployment.md#single-namespace-vs-multi-namespace), in [Deployment Guide](12-deployment.md) | `kates deploy --topology isolated`, the default, gives Kafka, the Kates API and the chaos tooling their own namespaces (`kafka`, `kates`, `litmus`), `--topology single` puts them in one (`kates-stack` by default), and the operator goes to `strimzi-operator` either way. | `gl-isolated-topology`; also `gl-single-namespace-topology` |
| PrometheusRule alerts and their runbooks | [PrometheusRule Alerts](20-installation-guide.md#prometheusrule-alerts), in [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md) | The `kafka-cluster` chart renders its alerts as a PrometheusRule where the Prometheus Operator's API exists, and each rule's `runbook_url` points at its entry in `docs/kafka-cluster-runbook.md`. | `gl-prometheusrule` |
| Topics and users as code | [Topics & Users Reference](20-installation-guide.md#topics--users-reference), in [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md) | The `kafka-cluster` chart turns each entry under `topics.items` and `users.items` into a Strimzi `KafkaTopic` or `KafkaUser` resource, which the Entity Operator applies to the cluster. | `gl-kafkatopic`; also `gl-kafkauser` |
Expand Down
4 changes: 3 additions & 1 deletion docs/book/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Reading order is defined by [`_quarto.yml`](_quarto.yml) — filenames are stabl
| [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md) | Step-by-step Kafka deployment with prerequisites and verification |
| [Kafka Deployment Engineering](15-kafka-deployment.md) | The engineering rationale: Strimzi, KRaft, broker tuning, and operations |
| [Deployment Guide](12-deployment.md) | Deploying the Kates stack: topology decisions, sizing, and cloud guidance |
| [Running Kates Under the Kates Operator](kates-operator.md) | The Kates API as a quorum under the operator: failover, drained upgrades, lost nodes; standalone stays the default |
| [Compliance Checks](compliance.md) | A reference architecture as a file, and checks that hold the live cluster to it |
| [Security & Compliance](17-security.md) | Authentication, authorization, certificates, network policies, and Kyverno |
| [Multi-Tenancy](19-multi-tenancy.md) | Topic naming, service onboarding, quotas, and tenant isolation |
Expand Down Expand Up @@ -119,7 +120,8 @@ Don't read this book cover-to-cover. Pick a reading path based on what you need:
### 🚀 "I want to deploy Kates"
1. [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md) — full step-by-step with prerequisites (~30 min)
2. [Deployment Guide](12-deployment.md) — architecture decisions, resource sizing, cloud deployment (~15 min)
3. [The Cluster Under Test](03-cluster.md) — understanding what you just deployed (~10 min)
3. [Running Kates Under the Kates Operator](kates-operator.md) — optional: the Kates API as a quorum that survives a lost node or an upgrade (~20 min)
4. [The Cluster Under Test](03-cluster.md) — understanding what you just deployed (~10 min)

### 💥 "I want to run chaos experiments"
1. [Chaos Engineering Theory](06-chaos-theory.md) — principles and methodology (~10 min)
Expand Down
1 change: 1 addition & 0 deletions docs/book/_quarto.yml
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ book:
- 20-installation-guide.md
- 15-kafka-deployment.md
- 12-deployment.md
- kates-operator.md
- compliance.md
- 17-security.md
- 19-multi-tenancy.md
Expand Down
4 changes: 4 additions & 0 deletions docs/book/appendix-a-glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,10 @@ The Kafka Advanced Testing & Engineering Suite, in two halves: the `kates` CLI o

The Kates server: the Quarkus application that serves the REST and gRPC APIs, runs benchmark backends and faults, and stores results. The `kates` chart deploys it as the `kates` Deployment and Service, serving REST and gRPC on port 8080, in the `kates` namespace under the isolated topology; `make ports` forwards it to `localhost:30083`. See [Architecture & Design](02-architecture.md#high-level-architecture).

### Kates Operator {#gl-kates-operator}

A Kubernetes operator: a controller that runs an application from a custom resource describing it. In Kates, it runs the Kates API from a `Kates` resource, as one member or as a quorum of three or five whose leader takes the writes, and drains live runs before an upgrade; `kates deploy --kates-mode operator` installs it, and the standalone `kates` chart stays the default. See [Running Kates Under the Kates Operator](kates-operator.md).

### Kind {#gl-kind}

Kubernetes IN Docker: a tool that runs a Kubernetes cluster in Docker containers, one container per node. `make cluster` creates the `panda` cluster with it. See [Deployment Guide](12-deployment.md#kubernetes-cluster).
Expand Down
2 changes: 1 addition & 1 deletion docs/book/appendix-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -419,7 +419,7 @@ Every term the book teaches, with the sections that teach it: the ones that use
## Q

[Quorum]{#idx-quorum}
: [The Cluster Under Test](03-cluster.md): [Kafka You Need for This Book](03-cluster.md#kafka-you-need-for-this-book), [Replication Configuration](03-cluster.md#replication-configuration); [Observability & Monitoring](09-observability.md): [The Dashboard Set](09-observability.md#the-dashboard-set); [Kafka Deployment Engineering](15-kafka-deployment.md): [Cluster Architecture](15-kafka-deployment.md#cluster-architecture); [Compliance Checks](compliance.md): [Writing Constraints](compliance.md#writing-constraints), [Placing Pods Across Zones and Nodes](compliance.md#placing-pods-across-zones-and-nodes); [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands); [REST API Reference](11-api-reference.md): [Endpoints](11-api-reference.md#endpoints)
: [Kafka Deployment Engineering](15-kafka-deployment.md): [Cluster Architecture](15-kafka-deployment.md#cluster-architecture); [Running Kates Under the Kates Operator](kates-operator.md): [Standalone Stays the Default](kates-operator.md#standalone-stays-the-default), [Reading the Kates Resource](kates-operator.md#reading-the-kates-resource), [The Quorum](kates-operator.md#the-quorum), [Limits](kates-operator.md#limits); [Compliance Checks](compliance.md): [Writing Constraints](compliance.md#writing-constraints), [Placing Pods Across Zones and Nodes](compliance.md#placing-pods-across-zones-and-nodes); [REST API Reference](11-api-reference.md): [Endpoints](11-api-reference.md#endpoints)

[Quota]{#idx-quota}
: [Kafka Deployment Engineering](15-kafka-deployment.md): [Broker Settings and Why](15-kafka-deployment.md#broker-settings-and-why); [Multi-Tenancy](19-multi-tenancy.md): [How Quotas Work](19-multi-tenancy.md#how-quotas-work), [Monitoring a Tenant](19-multi-tenancy.md#monitoring-a-tenant)
Expand Down
Loading
Loading