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
44 changes: 23 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,33 +86,35 @@ docker compose down -v

### Multi-zone Kubernetes lab (Kind)

This path builds the whole stack on a local Kind cluster. You need:
This path builds the whole stack on a local Kind cluster, from the released CLI. It needs no clone of this repository. You need:

- a clone of this repository, for the `make` targets, which are read relative to the working directory, so run every command from the repository root;
- Docker (any daemon the `docker` CLI talks to), [Kind](https://kind.sigs.k8s.io/), `kubectl` and Helm, at the minimum versions in the book's [Prerequisites](docs/book/12-deployment.md#prerequisites);
- Docker, running (Docker Desktop, OrbStack or Colima on macOS, Docker Engine on Linux), [Kind](https://kind.sigs.k8s.io/), `kubectl` and Helm, at the minimum versions in the book's [Prerequisites](docs/book/12-deployment.md#prerequisites);
- about 16 GB of RAM, with at least 10 GB of it available to Docker, on macOS or Linux (amd64 or arm64).

```bash
# 1. The CLI (macOS or Linux), and a checkout of the same release for the make targets
brew install bmscomp/tap/kates
git clone https://github.com/bmscomp/kates && cd kates
git checkout "$(git describe --tags --abbrev=0 --match 'v*')"
# 1. The tools and the CLI, with Homebrew on macOS or Linux (the kates formula also installs cosign)
brew install kind kubectl helm bmscomp/tap/kates

# 2. A three-zone Kind cluster named panda, and the release's native backend image loaded into it
make cluster
make kates-native

# 3. The stack: a wizard on a terminal; --dry-run prints the plan and installs nothing
# 2. The stack: with no cluster reachable, deploy offers to create panda, a three-zone Kind cluster;
# --dry-run prints the plan and installs nothing
kates deploy

# 4. Port-forwards in the background; a CLI context named ports, with the API URL and key, becomes current
# 3. Port-forwards in the background; a CLI context named ports, with the API URL and key, becomes current
kates ports

# 5. A first load test
# 4. A first load test
kates health
kates test create --type LOAD --records 100000 --wait
```

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.txt` (`INSTALL_DIR` changes where it goes, `/usr/local/bin` by default):

```bash
curl -fsSL https://raw.githubusercontent.com/bmscomp/kates/main/scripts/install-kates.sh | bash
```

Or download `kates-<os>-<arch>.tar.gz` from the [latest release](https://github.com/bmscomp/kates/releases/latest): it holds a single `kates` binary. Install [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) too, so `kates deploy` can check the signatures of the charts it pulls.

Run a CI quality gate against a minimum grade:

```bash
Expand All @@ -122,11 +124,11 @@ kates gate --min-grade C --records 100000
<details>
<summary><strong>Notes on releases, cluster contexts, images and API keys</strong></summary>

- **Release or `main`.** Homebrew, the release tarballs and `make kates-native` all give the latest release, so step 1 checks out that release's charts to match. Without Homebrew, download `kates-<os>-<arch>.tar.gz` from the [latest release](https://github.com/bmscomp/kates/releases/latest); it holds a single `kates` binary. The Homebrew `kates` installs the charts its release published, the same versions as the tag you check out; a `kates` built from source installs the checkout's charts. To run `main` instead, skip the `git checkout` and build both halves from the checkout: `make cli-install` for the CLI and `make kates-image-native-local` for the Kates API image (see [Building from source](#building-from-source)).
- **Which cluster.** `kates deploy` installs into kubectl's current context. `make cluster` switches that to `kind-panda` only when it creates the cluster, so check `kubectl config current-context` and run `kubectl config use-context kind-panda` if needed. Before deploying, `kates deploy` probes every context in your kubeconfig: with none reachable it offers to create the Kind cluster, and with several it asks which one, but it does not switch to the one you pick. `-y` never prompts, so it fails where it would have asked.
- **The backend image.** On Kind, `kates deploy` runs a local native image, `kates:native-local` if present and otherwise `kates:native`, and never pulls one. Without either, the deploy stops at the backend step, after Kafka and monitoring are installed. `make kates-native` pulls the published image of the release that `charts/kates/Chart.yaml` names, and compiles one only if the pull fails; it keeps a `kates:native` already on the machine, so run `docker rmi kates:native` first when you change releases. `make kates-image-native-local` compiles your working tree instead (several minutes, about 8 GB of Docker memory). Both load the image into `panda`, so create the cluster first.
- **Release charts.** A released `kates`, from Homebrew, the installer or a tarball, installs the charts its release published to `oci://ghcr.io/bmscomp/charts`, at the versions of its tag, and checks their signatures. `brew upgrade bmscomp/tap/kates` moves to a newer release. To run `main` or a change of your own, build from a checkout instead (see [Building from source](#building-from-source)).
- **Which cluster.** `kates deploy` installs into kubectl's current context. Before deploying, it probes every context in your kubeconfig: with none reachable it offers to create the Kind cluster `panda`, and with several it asks which one. The cluster it deploys to becomes kubectl's current context, and it prints the command that switches back. `-y` never prompts, so it fails where it would have asked.
- **The backend image.** On Kind, `kates deploy` runs a local native image when one is in Docker or on the nodes, `kates:native-local` and then `kates:native`, which a source build leaves there. Without one, the nodes pull the published native image of the release.
- **The API key.** Every `/api` call except `/api/health` needs the key from Secret `kates-api-key` in namespace `kates` (`kates-stack` with `--topology single`). `kates deploy` writes it into the active CLI context unless that context already holds a key kates did not put there, and `kates ports` into a context of its own, `ports`; a context you create yourself needs `--api-key`. Because `/api/health` is public, a green `kates health` does not prove the key works; `kates test list` does.
- **`make all`** is an interactive wrapper: it creates the Kind cluster if no cluster is reachable, asks for a topology, runs `kates deploy` and then the `make ports` script, which uses the second port map below. With the single-namespace topology that script finds nothing to forward, so run `kates ports` afterwards. It uses the `kates` on your `PATH` and does not fetch the backend image, so do step 1 and `make cluster && make kates-native` first.
- **`make all`**, in a checkout, is an interactive wrapper for contributors: it creates the Kind cluster if no cluster is reachable, asks for a topology, runs `kates deploy` with the checkout's charts and then the `make ports` script, which uses the second port map below.

</details>

Expand Down Expand Up @@ -172,8 +174,8 @@ Kafka UI can only read: its Kafka user has Describe and Read ACLs, so the broker
### Tear down

```bash
kates clean --force # uninstall the stack and keep the cluster; without --force it asks first
make destroy # delete the Kind cluster panda (FORCE=1 skips the prompt)
kates clean --force # uninstall the stack and keep the cluster; without --force it asks first
kind delete cluster --name panda # delete the Kind cluster panda
```

`kates clean` works on kubectl's current context and names it before asking. It removes the Strimzi, Litmus, Prometheus Operator, cert-manager and Kyverno CRDs, and the cert-manager, Kyverno and Strimzi operators, unless objects of their kinds exist outside the namespaces it deletes; it keeps a namespace that also holds a Helm release it does not install. It lists what it keeps and why. Once you confirm, it stops the `kubectl port-forward` processes into the namespaces it deletes.
Expand Down Expand Up @@ -302,7 +304,7 @@ A published version is never pushed again, so its digest does not change.

## Building from source

You need Go and a JDK at the versions in the [version matrix](docs/book/appendix-d-versions.md), plus Docker for images and integration tests. Under the default `GOTOOLCHAIN=auto`, Go downloads the toolchain that `cli/go.mod` names, and `./mvnw` downloads Maven.
Build from source to work on Kates itself: to change the code, debug it or contribute. To use Kates, install the released CLI as the [quick start](#multi-zone-kubernetes-lab-kind) does. You need Go and a JDK at the versions in the [version matrix](docs/book/appendix-d-versions.md), plus Docker for images and integration tests. Under the default `GOTOOLCHAIN=auto`, Go downloads the toolchain that `cli/go.mod` names, and `./mvnw` downloads Maven.

```bash
make cli-install # Build the CLI with version info; installs to /usr/local/bin (CLI_INSTALL_DIR to change)
Expand Down
42 changes: 16 additions & 26 deletions docs/book/01-introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,59 +83,49 @@ Kates is both a check before a merge (a short LOAD run) and the gate before prod

You run the payments platform, and before it moves onto [`krafter`](appendix-a-glossary.md#gl-krafter), the Kafka cluster under test, you have to say whether the cluster can carry it. The book turns that into targets a Kates run can check. `krafter` must take 2,000 records per second of 1 KiB with `acks=all`, and answer writes with a P99 of 100 ms or less from send to acknowledgment. It must also lose no acknowledged record when one broker or one zone fails.

The Quick Start takes the first step: a LOAD run against `krafter` and its report. It assumes a checkout of the repository, for the `make` targets, and a stack that `make all` deployed in the [isolated topology](appendix-a-glossary.md#gl-isolated-topology), which puts the Kates API in the `kates` namespace and `krafter` in `kafka`. In the book's lab that stack runs on [`panda`](appendix-a-glossary.md#gl-panda), the three-node Kind cluster. Each step says what success looks like and where to go when it fails; the [CLI Issues](appendix-b-troubleshooting.md#cli-issues) in the Troubleshooting Index cover most of the failures.
The Quick Start takes the first step: a LOAD run against `krafter` and its report. It installs the released CLI and deploys the stack in the [isolated topology](appendix-a-glossary.md#gl-isolated-topology), which puts the Kates API in the `kates` namespace and `krafter` in `kafka`. In the book's lab that stack runs on [`panda`](appendix-a-glossary.md#gl-panda), the three-node Kind cluster. It needs no checkout of the repository. Each step says what success looks like and where to go when it fails; the [CLI Issues](appendix-b-troubleshooting.md#cli-issues) in the Troubleshooting Index cover most of the failures.

1. Build and install the CLI.
1. Install Kind, kubectl, Helm and the CLI, on macOS or Linux, with Docker running and about 16 GB of RAM available to it.

```bash
make cli-install
brew install kind kubectl helm bmscomp/tap/kates
```

The target prints `✅ Installed:` and the version of the binary it wrote, then warns if `kates` on your `PATH` is another binary. When it refuses to write through a symlink another package owns, rerun it with `CLI_INSTALL_DIR=$HOME/.local/bin`, as its message says. If `kates` is then killed at once (exit 137) on macOS, see [CLI Binary Killed on macOS](12-deployment.md#cli-binary-killed-on-macos).
`kates version` then prints the release. The `kates` formula also installs cosign, which checks the charts the deploy pulls. Without Homebrew, [Installation](10-cli-reference.md#installation) in CLI Reference gives the release installer and the archives.

2. Forward the Kates API to `localhost:30083`, in the background.
2. Deploy the stack.

```bash
make ports
kates deploy --topology isolated
```

Success is a `Forwarding Kates API: http://localhost:30083` line and a closing `Port forwarding: N active, M skipped` line. `nothing was forwarded` means nothing is deployed in the namespaces it looked in: check that `make all` finished, or set `KATES_NS` as the single-namespace note below says.
With no cluster reachable, it offers to create `panda` and switches kubectl to it; accept. With a cluster reachable, it deploys into kubectl's current context, so check `kubectl config current-context` first. Success is a summary of the installed components and their access points. After a failure, fix the cause and run it again: it skips or upgrades the components already installed.

3. Read the [API key](appendix-a-glossary.md#gl-api-key) the `kates` chart generated into the `kates-api-key` [Secret](appendix-a-glossary.md#gl-secret).
3. Forward the services in the background, and connect the CLI.

```bash
KEY=$(kubectl get secret kates-api-key -n kates \
-o jsonpath='{.data.api-key}' | base64 -d)
kates ports
```

The command prints nothing; `echo "${#KEY}"` printing a number above 0 shows the key arrived. A `NotFound` error usually means the Secret is in another namespace, such as `kates-stack`.
It forwards the Kates API to `localhost:8080`, reads the [API key](appendix-a-glossary.md#gl-api-key) the `kates` chart generated into the `kates-api-key` [Secret](appendix-a-glossary.md#gl-secret), and writes both into a [CLI context](appendix-a-glossary.md#gl-cli-context) named `ports`, which it makes current. It says when the API rejects the key.

4. Create a [CLI context](appendix-a-glossary.md#gl-cli-context) with that key, and make it current.

```bash
kates ctx set local --url http://localhost:30083 --api-key "$KEY"
kates ctx use local
```

Success is `Context 'local' → http://localhost:30083`, then `Switched to 'local' → http://localhost:30083`. `--api-key was given but is empty` means step 3 found no key: repeat it.

5. Check that the CLI reaches the Kates API and the Kates API reaches `krafter`.
4. Check that the CLI reaches the Kates API and the Kates API reaches `krafter`.

```bash
kates health
```

The banner reads `System Status: UP`, and the Kafka Cluster section shows the bootstrap address. `DEGRADED` means the Kates API can't reach Kafka: see [Kates Can't Connect to Kafka](12-deployment.md#kates-cant-connect-to-kafka). A refused connection means the forward from step 2 died: run `make ports` again.
The banner reads `System Status: UP`, and the Kafka Cluster section shows the bootstrap address. `DEGRADED` means the Kates API can't reach Kafka: see [Kates Can't Connect to Kafka](12-deployment.md#kates-cant-connect-to-kafka). A refused connection means the forward from step 3 died: run `kates ports` again.

6. Run your first test, and wait for it to finish.
5. Run your first test, and wait for it to finish.

```bash
kates test create --type LOAD --records 100000 --wait
```

It prints `Test created successfully` and the run's ID, then exits 0 when the run is done. An error that starts `[401] Missing API key` means the context has no key: repeat steps 3 and 4. A run that ends `FAILED` prints the `kates test get <id>` command that shows why.
It prints `Test created successfully` and the run's ID, then exits 0 when the run is done. An error that starts `[401] Missing API key` means the context has no key: repeat step 3. A run that ends `FAILED` prints the `kates test get <id>` command that shows why.

7. Read the run's report, with the ID that step 6 printed.
6. Read the run's report, with the ID that step 5 printed.

```bash
kates report show <id>
Expand All @@ -145,7 +135,7 @@ The Quick Start takes the first step: a LOAD run against `krafter` and its repor

Every `/api` endpoint except `/api/health` needs the API key, which is why `kates ctx set` takes `--api-key` and why `kates health` works before the key is set.

`kates ports` does steps 2 to 4 at once: it forwards the API to `localhost:8080`, creates a CLI context named `ports` with the key from the Secret and makes it current. With the [single-namespace topology](appendix-a-glossary.md#gl-single-namespace-topology) (option 1 in `make all`), the Secret lives in `kates-stack`: use `-n kates-stack` in step 3, and `KATES_NS=kates-stack make ports` in step 2. The [Deployment Guide](12-deployment.md) covers how `kates deploy` fills a context's key.
To connect without `kates ports`, forward the API yourself and create a context with the key: `kubectl get secret kates-api-key -n kates -o jsonpath='{.data.api-key}' | base64 -d` reads it, and `kates ctx set <name> --url <url> --api-key <key>` stores it. With the [single-namespace topology](appendix-a-glossary.md#gl-single-namespace-topology) (`--topology single`), the Secret lives in `kates-stack`. The [Deployment Guide](12-deployment.md) covers how `kates deploy` fills a context's key.

The report also has an SLA section, which reads `All SLA thresholds met` unless the run missed a threshold it carried. The payments targets are judged on the `produce` row of `kates test get <id>`: its throughput, and its P99, which times each write from send to acknowledgment. This first run carries no targets yet: Part II writes them into a scenario file whose gates check them.

Expand Down
2 changes: 1 addition & 1 deletion docs/book/03-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,7 @@ The table gives the address and credentials of each service you open from your m
| [Kafka UI](appendix-a-glossary.md#gl-kafka-ui) | http://localhost:30081 | none |
| Kates API | http://localhost:30083 | [API key](appendix-a-glossary.md#gl-api-key) from the `kates-api-key` [Secret](appendix-a-glossary.md#gl-secret) |

The `localhost` addresses are the local ends of the port-forwards that `make ports` starts in the background; `panda` does not publish its NodePorts on the host, so nothing answers on them until it runs. The [Quick Start](01-introduction.md#quick-start) in Introduction sets up the port-forward and a [CLI context](appendix-a-glossary.md#gl-cli-context) carrying the API key.
The `localhost` addresses are the local ends of the port-forwards that `make ports` starts in the background from a checkout; `panda` does not publish its NodePorts on the host, so nothing answers on them until it runs. `kates ports`, which the [Quick Start](01-introduction.md#quick-start) in Introduction runs, forwards the Kates API to `localhost:8080` and Grafana to `localhost:3000` instead, and makes current a [CLI context](appendix-a-glossary.md#gl-cli-context) carrying the API key.

::: {.callout-important title="make ports looks only in the kafka namespace"}
`make ports` looks for Grafana, and for Prometheus, which it forwards to `localhost:30090`, only in the `kafka` namespace, where `make monitoring` installs them. `kates deploy`, and so `make all`, installs the monitoring stack into the `monitoring` namespace, where `make ports` skips both with a "not deployed in namespace 'kafka'" line. On that install, run `MONITORING_NS=monitoring make ports` instead, or `kates ports`, which forwards Grafana to `localhost:3000` and Prometheus to `localhost:30090`.
Expand Down
Loading
Loading