diff --git a/README.md b/README.md
index eb32a90a..b1311ae6 100644
--- a/README.md
+++ b/README.md
@@ -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--.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
@@ -122,11 +124,11 @@ kates gate --min-grade C --records 100000
Notes on releases, cluster contexts, images and API keys
-- **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--.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.
@@ -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.
@@ -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)
diff --git a/docs/book/01-introduction.md b/docs/book/01-introduction.md
index 90f5d25a..6fc7f415 100644
--- a/docs/book/01-introduction.md
+++ b/docs/book/01-introduction.md
@@ -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 ` 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 ` 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
@@ -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 --url --api-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 `: 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.
diff --git a/docs/book/03-cluster.md b/docs/book/03-cluster.md
index 4c960952..51ab94cf 100644
--- a/docs/book/03-cluster.md
+++ b/docs/book/03-cluster.md
@@ -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`.
diff --git a/docs/book/10-cli-reference.md b/docs/book/10-cli-reference.md
index c885c5d8..3f845175 100644
--- a/docs/book/10-cli-reference.md
+++ b/docs/book/10-cli-reference.md
@@ -21,16 +21,27 @@ Example IDs, such as `3f8a2c1e`, have the eight hexadecimal characters the Kates
## Installation
-The CLI is one binary. Install it in one of three ways:
+The CLI is one binary, released for macOS and Linux on amd64 and arm64. Install a release in one of three ways:
-- With Homebrew, `brew install bmscomp/tap/kates`, which also installs cosign.
-- From the GitHub Release, by downloading the archive for your platform and putting `kates` on your `PATH`.
-- From a checkout of the repository, with `make cli-install`, which builds and installs it.
+- With Homebrew, on macOS or Linux: `brew install bmscomp/tap/kates`, which also installs cosign. `brew upgrade bmscomp/tap/kates` moves to a newer release.
+- With the release installer, which downloads the archive for your platform, checks it against the release's `checksums.txt` and puts `kates` in `/usr/local/bin` (`INSTALL_DIR` changes it):
+
+ ```bash
+ curl -fsSL \
+ https://raw.githubusercontent.com/bmscomp/kates/main/scripts/install-kates.sh \
+ | bash
+ ```
+
+- From the [GitHub Release](https://github.com/bmscomp/kates/releases/latest), by downloading `kates--.tar.gz` and putting the `kates` it holds on your `PATH`.
+
+Without Homebrew, install [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) as well, so `kates deploy` can check the charts it pulls. To deploy the lab, the CLI also needs Docker, Kind, kubectl and Helm: [Prerequisites](12-deployment.md#prerequisites) in the Deployment Guide lists them.
+
+To work on Kates itself, build the CLI from a checkout of the repository with `make cli-install`, which builds and installs it.
The [Version & Compatibility Matrix](appendix-d-versions.md) gives the versions each release pins.
::: {.callout-note title="Installing on macOS by hand"}
-A binary copied into place by hand keeps the `com.apple.provenance` and `com.apple.quarantine` attributes, and the kernel can kill it on start. `make cli-install` strips them and ad-hoc signs the binary. Otherwise run `sudo xattr -dr com.apple.provenance /usr/local/bin/kates`, the same for `com.apple.quarantine`, and `sudo codesign -f -s - /usr/local/bin/kates`.
+A binary copied into place by hand, from a release archive, keeps the `com.apple.provenance` and `com.apple.quarantine` attributes, and the kernel can kill it on start. `make cli-install` strips them and ad-hoc signs the binary. Otherwise run `sudo xattr -dr com.apple.provenance /usr/local/bin/kates`, the same for `com.apple.quarantine`, and `sudo codesign -f -s - /usr/local/bin/kates`.
:::
## Where to Start {#common-workflows}
diff --git a/docs/book/12-deployment.md b/docs/book/12-deployment.md
index c619492e..0f6e388b 100644
--- a/docs/book/12-deployment.md
+++ b/docs/book/12-deployment.md
@@ -1,6 +1,6 @@
# Deployment Guide
-The first `make all` asks you one question — one namespace or several — and the answer decides who may read your Kafka credentials, what a chaos experiment can take down, and whether `kubectl delete namespace` is a teardown or an outage. This chapter is about that question and the two beside it: how you expose the stack and where its data lives. A deployment tuned for local experimentation buckles under production load; a production layout is needless overhead on a laptop.
+The first `kates deploy` asks you one question — one namespace or several — and the answer decides who may read your Kafka credentials, what a chaos experiment can take down, and whether `kubectl delete namespace` is a teardown or an outage. This chapter is about that question and the two beside it: how you expose the stack and where its data lives. A deployment tuned for local experimentation buckles under production load; a production layout is needless overhead on a laptop.
::: {.callout-note title="Scope"}
This chapter deploys the Kates stack: the [Kates API](appendix-a-glossary.md#gl-kates-api), the CLI, monitoring and chaos tooling, and the layout between them. Provisioning [`krafter`](appendix-a-glossary.md#gl-krafter), the Kafka cluster under test, is [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md), and its rationale is [Kafka Deployment Engineering](15-kafka-deployment.md).
@@ -11,7 +11,7 @@ After this chapter, you can:
- Choose a topology — namespace layout, service exposure, storage durability — that fits your environment
- Size CPU, memory, and disk per component so your tests measure Kafka, not resource contention
- Adapt the stack to EKS, GKE, or AKS with provider-specific [values overlays](appendix-a-glossary.md#gl-values-overlay)
-- Deploy everything with `make all` and verify it with `make status` and `kates health`
+- Deploy everything with `kates deploy` and verify it with `kates health`
## Prerequisites
@@ -24,9 +24,17 @@ The lab needs these tools on your machine. The versions it is tested with are in
| kubectl | Kubernetes CLI |
| Helm | Kubernetes package manager |
| jq | JSON processing (optional) |
-| Go | CLI compilation (if building from source) |
-| Java | Kates API compilation (if building from source) |
-| Maven | Kates API build (bundled as `mvnw`) |
+| Kates CLI | Deploys and drives the stack |
+
+On macOS, and on Linux with Homebrew, one command installs the last four:
+
+```bash
+brew install kind kubectl helm bmscomp/tap/kates
+```
+
+For Docker, use Docker Desktop, OrbStack or Colima on macOS, and Docker Engine on Linux. The `kates` formula also installs cosign, which checks the signatures of the charts `kates deploy` pulls. Without Homebrew, install Kind, kubectl and Helm from their own install pages, and the CLI as [Installation](10-cli-reference.md#installation) in CLI Reference describes.
+
+Go, a JDK and Maven are needed only to build Kates from source, to work on it; [Building from Source](#building-from-source) covers that path.
## Deployment Architecture Decisions
@@ -164,13 +172,27 @@ The Minimal profile (16 GB) runs everything but leaves almost no headroom. If yo
## Quick Deployment
-One command deploys everything:
+One command deploys everything, with the CLI that Homebrew installed and no checkout of the repository:
```bash
-make all
+kates deploy
```
-`make all` drives the deployment through the Kates CLI itself. In order, it:
+In order, it:
+
+1. Checks that kubectl and helm are installed.
+2. Uses the reachable cluster, asks which one when several are reachable, or offers to build the Kind cluster `panda` when none is.
+3. Asks whether you want a single namespace (`kates-stack`) or isolated namespaces, unless `--topology` names one.
+4. Pulls the charts its release published to `oci://ghcr.io/bmscomp/charts`, checks their signatures, and installs them.
+5. Writes the API key into the active CLI context and prints the access points.
+
+Then `kates ports` forwards the service ports and makes a CLI context named `ports` current. `--dry-run` prints the plan and installs nothing.
+
+On Kind, the Kates API runs a local [native image](appendix-a-glossary.md#gl-graalvm-native-image) when Docker or the nodes hold one, `kates:native-local` and then `kates:native`, as a source build leaves them; without one, the nodes pull the release's published native image.
+
+### Building from Source
+
+To work on Kates itself, deploy from a checkout instead. `make all` is the interactive wrapper for that path. In order, it:
1. Checks that kubectl and helm are installed.
2. Uses the reachable cluster, or builds the Kind cluster `panda` when none is reachable.
@@ -180,9 +202,7 @@ make all
6. Runs `scripts/port-forward.sh` to expose the service ports.
7. Prints the access points.
-Because `make all` sets `KATES_CHECKOUT` to the checkout, a `kates` installed from Homebrew deploys this checkout's charts rather than the ones its release published.
-
-On Kind, `kates deploy` needs a [native image](appendix-a-glossary.md#gl-graalvm-native-image) of the Kates API, `kates:native-local` or `kates:native`, in local Docker or on the node, and stops at the Kates API step without one. `make kates-native` pulls the published image or builds it and loads it into the cluster; then run `make all` again.
+Because `make all` sets `KATES_CHECKOUT` to the checkout, even a `kates` installed from Homebrew deploys this checkout's charts rather than the ones its release published. `make kates-image-native-local` compiles the working tree's backend into `kates:native-local` and loads it into the cluster, which `kates deploy` then prefers. The [Kates CLI](#kates-cli) targets build the CLI.
## Component-by-Component Deployment
@@ -439,7 +459,7 @@ These `emptyDir` volumes don't survive pod restarts, which is safe: `/var/run/po
### Kates CLI
-The CLI targets build, install and clean the `kates` binary:
+To use the CLI, install a release: `brew install bmscomp/tap/kates`, or another way from [Installation](10-cli-reference.md#installation) in CLI Reference. To work on it, the CLI targets build, install and clean the `kates` binary from a checkout:
```bash
# Build + install locally
@@ -459,9 +479,11 @@ On macOS, `make cli-install` also strips the provenance and quarantine extended
After deployment, set up port forwarding:
```bash
-make ports
+kates ports
```
+From a checkout, `make ports` forwards the same services to the other port map that [Access Points](03-cluster.md#access-points) lists.
+
For the full list of access points and URLs, see [Access Points](03-cluster.md#access-points) in The Cluster Under Test.
## CLI Configuration
@@ -1283,13 +1305,9 @@ Pods stuck in `Pending` mean the scheduler can't satisfy zone affinity or provis
### CLI Binary Killed on macOS
-If `kates health` is immediately killed (exit code 137), macOS is blocking the unsigned binary:
+If `kates health` is immediately killed (exit code 137), macOS is blocking a binary copied into place by hand, from a release archive. `brew reinstall bmscomp/tap/kates` replaces it with one macOS runs. From a checkout, `make cli-install` strips the attributes and signs the binary it builds. Otherwise:
```bash
-# Fix: reinstall with codesigning
-make cli-install
-
-# Or manually
sudo xattr -dr com.apple.provenance /usr/local/bin/kates
sudo xattr -dr com.apple.quarantine /usr/local/bin/kates
sudo codesign -f -s - /usr/local/bin/kates
diff --git a/docs/book/appendix-index.md b/docs/book/appendix-index.md
index 4c2477d6..bcbc3b6a 100644
--- a/docs/book/appendix-index.md
+++ b/docs/book/appendix-index.md
@@ -91,7 +91,7 @@ Every term the book teaches, with the sections that teach it: the ones that use
: [Chaos Engineering Theory](06-chaos-theory.md): [Key Metrics During Chaos](06-chaos-theory.md#key-metrics-during-chaos); [Observability & Monitoring](09-observability.md): [Alerting](09-observability.md#alerting); [Kafka Deployment Engineering](15-kafka-deployment.md): [Operational Components](15-kafka-deployment.md#operational-components)
[Context]{#idx-context}
-: [Preface](index.qmd): [Before You Start](index.qmd#before-you-start); [Introduction](01-introduction.md): [Quick Start](01-introduction.md#quick-start); [Architecture & Design](02-architecture.md): [High-Level Architecture](02-architecture.md#high-level-architecture); [Deployment Guide](12-deployment.md): [CLI Configuration](12-deployment.md#cli-configuration); [CLI Reference](10-cli-reference.md): [Configuration](10-cli-reference.md#configuration), [Global Flags](10-cli-reference.md#global-flags), [Calling the Kates API](10-cli-reference.md#calling-the-kates-api), [Commands](10-cli-reference.md#commands)
+: [Introduction](01-introduction.md): [Quick Start](01-introduction.md#quick-start); [Architecture & Design](02-architecture.md): [High-Level Architecture](02-architecture.md#high-level-architecture); [Deployment Guide](12-deployment.md): [CLI Configuration](12-deployment.md#cli-configuration), [Kyverno Policies File](12-deployment.md#kyverno-policies-file); [CLI Reference](10-cli-reference.md): [Configuration](10-cli-reference.md#configuration), [Global Flags](10-cli-reference.md#global-flags), [Calling the Kates API](10-cli-reference.md#calling-the-kates-api), [Commands](10-cli-reference.md#commands)
[Controller]{#idx-controller}
: [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); [Chaos Engineering in Practice](07-chaos-practice.md): [Built-In Playbooks](07-chaos-practice.md#built-in-playbooks), [Safety Guardrails](07-chaos-practice.md#safety-guardrails); [Deploying the Strimzi Operator](deploying-strimzi-operator.md): [Adopting an Operator Installed from the Upstream Chart](deploying-strimzi-operator.md#migrating-from-the-ad-hoc-install); [Deployment Guide](12-deployment.md): [Cloud Deployment](12-deployment.md#cloud-deployment); [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)
@@ -100,7 +100,7 @@ Every term the book teaches, with the sections that teach it: the ones that use
: [Performance Theory](04-performance-theory.md): [Coordinated Omission](04-performance-theory.md#coordinated-omission)
[Cosign]{#idx-cosign}
-: [Deployment Guide](12-deployment.md): [Deploying Without GHCR](12-deployment.md#deploying-without-ghcr); [Security & Compliance](17-security.md): [Kyverno Policy Integration & Admission Control](17-security.md#kyverno-policy-integration--admission-control); [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands); [CI/CD Pipeline](appendix-c-cicd.md): Publish Kates Docker Image (`publish-docker.yml`)
+: [Deployment Guide](12-deployment.md): [Deploying Without GHCR](12-deployment.md#deploying-without-ghcr); [Security & Compliance](17-security.md): [Kyverno Policy Integration & Admission Control](17-security.md#kyverno-policy-integration--admission-control); [CLI Reference](10-cli-reference.md): [Installation](10-cli-reference.md#installation), [Commands](10-cli-reference.md#commands); [CI/CD Pipeline](appendix-c-cicd.md): Publish Kates Docker Image (`publish-docker.yml`)
[CRC32]{#idx-crc32}
: [Data Integrity Verification](08-data-integrity.md): [Sequence Number Tracking](08-data-integrity.md#sequence-number-tracking)
@@ -351,7 +351,7 @@ Every term the book teaches, with the sections that teach it: the ones that use
: [The Cluster Under Test](03-cluster.md): The Cluster Under Test, [Resource Budget](03-cluster.md#resource-budget)
[panda]{#idx-panda}
-: [Preface](index.qmd): [Before You Start](index.qmd#before-you-start); [The Cluster Under Test](03-cluster.md): [Physical Topology](03-cluster.md#physical-topology), [Operational Components](03-cluster.md#operational-components), [Changing the Topology for Different Scenarios](03-cluster.md#changing-the-topology-for-different-scenarios); [Performance Theory](04-performance-theory.md): [Why Latency Bends: Queues](04-performance-theory.md#why-latency-bends-queues); [Chaos Engineering Theory](06-chaos-theory.md): [Core Principles](06-chaos-theory.md#core-principles); [Kafka Deployment Engineering](15-kafka-deployment.md): [KafkaNodePool Configuration](15-kafka-deployment.md#kafkanodepool-configuration); [Compliance Checks](compliance.md): [Writing Constraints](compliance.md#writing-constraints)
+: [Preface](index.qmd): [Before You Start](index.qmd#before-you-start); [Introduction](01-introduction.md): [Quick Start](01-introduction.md#quick-start); [The Cluster Under Test](03-cluster.md): [Physical Topology](03-cluster.md#physical-topology), [Operational Components](03-cluster.md#operational-components), [Changing the Topology for Different Scenarios](03-cluster.md#changing-the-topology-for-different-scenarios); [Performance Theory](04-performance-theory.md): [Why Latency Bends: Queues](04-performance-theory.md#why-latency-bends-queues); [Chaos Engineering Theory](06-chaos-theory.md): [Core Principles](06-chaos-theory.md#core-principles); [Compliance Checks](compliance.md): [Writing Constraints](compliance.md#writing-constraints)
[Partition]{#idx-partition}
: [The Cluster Under Test](03-cluster.md): [Kafka You Need for This Book](03-cluster.md#kafka-you-need-for-this-book); [Chaos Engineering in Practice](07-chaos-practice.md): [Disruption Types](07-chaos-practice.md#disruption-types), [Built-In Playbooks](07-chaos-practice.md#built-in-playbooks), [Safety Guardrails](07-chaos-practice.md#safety-guardrails); [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md): Topics & Users Reference; [Kafka Deployment Engineering](15-kafka-deployment.md): [Operational Components](15-kafka-deployment.md#operational-components); [Multi-Tenancy](19-multi-tenancy.md): [How Quotas Work](19-multi-tenancy.md#how-quotas-work); [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands)
@@ -480,7 +480,7 @@ Every term the book teaches, with the sections that teach it: the ones that use
: [The Cluster Under Test](03-cluster.md): [Listeners](03-cluster.md#listeners); [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md): Kafka Listeners & Authentication, Topics & Users Reference; [Compliance Checks](compliance.md): [Kafka Settings and Monitoring](compliance.md#kafka-settings-and-monitoring); [Security & Compliance](17-security.md): [Authentication](17-security.md#authentication), [Network Policies](17-security.md#network-policies); [Kafka Connect & CDC Pipelines](21-kafka-connect.md): [The KafkaConnect Custom Resource](21-kafka-connect.md#the-kafkaconnect-custom-resource)
[Secret]{#idx-secret}
-: [Introduction](01-introduction.md): [Quick Start](01-introduction.md#quick-start); [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md): [Optional Features](20-installation-guide.md#advanced-features); [Kafka Deployment Engineering](15-kafka-deployment.md): [Troubleshooting](15-kafka-deployment.md#troubleshooting); [Deployment Guide](12-deployment.md): [CLI Configuration](12-deployment.md#cli-configuration); [Security & Compliance](17-security.md): [Authentication](17-security.md#authentication); [Operating Kafka Connect](operating-kafka-connect.md): Security & Credential Rotation, [Troubleshooting](operating-kafka-connect.md#troubleshooting); [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands)
+: [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md): [Optional Features](20-installation-guide.md#advanced-features); [Kafka Deployment Engineering](15-kafka-deployment.md): [Troubleshooting](15-kafka-deployment.md#troubleshooting); [Deployment Guide](12-deployment.md): [CLI Configuration](12-deployment.md#cli-configuration); [Security & Compliance](17-security.md): [Authentication](17-security.md#authentication); [Operating Kafka Connect](operating-kafka-connect.md): Security & Credential Rotation, [Troubleshooting](operating-kafka-connect.md#troubleshooting); [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands); [REST API Reference](11-api-reference.md): [Authentication](11-api-reference.md#authentication)
[Security Grade]{#idx-security-grade}
: [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands)
@@ -557,7 +557,7 @@ Every term the book teaches, with the sections that teach it: the ones that use
: [The Cluster Under Test](03-cluster.md): [Kafka You Need for This Book](03-cluster.md#kafka-you-need-for-this-book); [Scenario Files & SLA Gates](13-scenario-files.md): [Spec Reference](13-scenario-files.md#spec-reference); [Deploying the Strimzi Operator](deploying-strimzi-operator.md): [Adopting an Operator Installed from the Upstream Chart](deploying-strimzi-operator.md#migrating-from-the-ad-hoc-install); [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md): Topics & Users Reference; [Kafka Deployment Engineering](15-kafka-deployment.md): [Topic Provisioning](15-kafka-deployment.md#topic-provisioning); [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); [Compliance Language Reference](appendix-compliance-language.md): [Topics](appendix-compliance-language.md#topics)
[Topology]{#idx-topology}
-: [Introduction](01-introduction.md): [Quick Start](01-introduction.md#quick-start); [Architecture & Design](02-architecture.md): [High-Level Architecture](02-architecture.md#high-level-architecture); [The Cluster Under Test](03-cluster.md): [Physical Topology](03-cluster.md#physical-topology); [Deployment Guide](12-deployment.md): [Deployment Architecture Decisions](12-deployment.md#deployment-architecture-decisions), [Running Without Cluster Admin](12-deployment.md#running-without-cluster-admin); [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands); [Compliance Language Reference](appendix-compliance-language.md): [Settings](appendix-compliance-language.md#settings), [Brokers and Controllers](appendix-compliance-language.md#brokers-and-controllers)
+: [Preface](index.qmd): [Before You Start](index.qmd#before-you-start); [Introduction](01-introduction.md): [Quick Start](01-introduction.md#quick-start); [The Cluster Under Test](03-cluster.md): [Physical Topology](03-cluster.md#physical-topology); [Deployment Guide](12-deployment.md): [Deployment Architecture Decisions](12-deployment.md#deployment-architecture-decisions), [Running Without Cluster Admin](12-deployment.md#running-without-cluster-admin); [CLI Reference](10-cli-reference.md): [Commands](10-cli-reference.md#commands); [Compliance Language Reference](appendix-compliance-language.md): [Settings](appendix-compliance-language.md#settings), [Brokers and Controllers](appendix-compliance-language.md#brokers-and-controllers)
[Transactional Outbox]{#idx-transactional-outbox}
: [Architecture & Design](02-architecture.md): [Design Decisions](02-architecture.md#design-decisions), [Where Results Live](02-architecture.md#where-results-live)
diff --git a/docs/book/index.qmd b/docs/book/index.qmd
index dd57e211..c0afa114 100644
--- a/docs/book/index.qmd
+++ b/docs/book/index.qmd
@@ -87,7 +87,7 @@ You don't need to know Kafka's internals first. [The Cluster Under Test](03-clus
The Deployment Guide's [Prerequisites](12-deployment.md#prerequisites) table lists the tools the lab needs, with their versions. For the machine, [Installing Kafka with the kafka-cluster Helm Chart](20-installation-guide.md) asks for a Kubernetes cluster with at least 16 GB of memory and 6 CPU cores, and recommends 24 GB and 12 cores. On Kind, the memory and cores come from Docker.
-From a checkout of the repository, `make all` builds the lab. When your current `kubectl` context can't reach a cluster, it creates the `panda` Kind cluster first. It then asks you to choose a topology for Kafka, Kates and the chaos tooling: 1 puts them together in the `kates-stack` namespace, and 2 gives each a namespace of its own. Choose 2, which the Quick Start assumes. `kates deploy` then checks which clusters your kubeconfig reaches. When only the current context answers, it deploys there. When more than one answers, it asks which one to use, starting on the current context, and when only another cluster answers, it asks before deploying there. The cluster it deploys to becomes `kubectl`'s current context, and when that changes, `kates deploy` prints the `kubectl config use-context` command that switches back.
+The lab needs no checkout of the repository: Homebrew installs the tools and the CLI, `brew install kind kubectl helm bmscomp/tap/kates`, and `kates deploy --topology isolated` builds the lab from the charts its release published. The isolated topology gives Kafka, Kates and the chaos tooling a namespace each, which the Quick Start assumes; `--topology single` puts them together in `kates-stack`. When no cluster is reachable, `kates deploy` offers to create the `panda` Kind cluster first. Otherwise it checks which clusters your kubeconfig reaches. When only the current context answers, it deploys there. When more than one answers, it asks which one to use, starting on the current context, and when only another cluster answers, it asks before deploying there. The cluster it deploys to becomes `kubectl`'s current context, and when that changes, `kates deploy` prints the `kubectl config use-context` command that switches back.
Two names recur throughout the book. `panda` is the Kind cluster: its three nodes are named after the zones they stand for, `alpha`, `sigma` and `gamma`, and Kafka spreads its brokers across them. `krafter` is the Kafka cluster under test, which [The Cluster Under Test](03-cluster.md) describes.
diff --git a/docs/book/part-foundations.md b/docs/book/part-foundations.md
index 5327bc21..3bdf4733 100644
--- a/docs/book/part-foundations.md
+++ b/docs/book/part-foundations.md
@@ -10,7 +10,7 @@ The three chapters go from the tool, to how it works, to the cluster it tests:
- [Architecture & Design](02-architecture.md): where does each part of Kates run, and what happens between `kates test create` and the report? About 10 minutes.
- [The Cluster Under Test](03-cluster.md): how do `krafter`'s replication settings and its ~2Gi page cache budget shape every latency number you measure? About 15 minutes.
-If you'd rather take the [Quick Start](01-introduction.md#quick-start) one step at a time, [Tutorial 1: Getting Started with Kates](../tutorials/01-getting-started.md) goes from `make all` to a first report, then exports the report and compares two runs with `kates report diff`.
+If you'd rather take the [Quick Start](01-introduction.md#quick-start) one step at a time, [Tutorial 1: Getting Started with Kates](../tutorials/01-getting-started.md) goes from `brew install` to a first report, then exports the report and compares two runs with `kates report diff`.
## The Payments Question
diff --git a/docs/tutorials/01-getting-started.md b/docs/tutorials/01-getting-started.md
index f3ff3b31..2f47149e 100644
--- a/docs/tutorials/01-getting-started.md
+++ b/docs/tutorials/01-getting-started.md
@@ -2,56 +2,55 @@
This tutorial walks you through deploying the Kates stack, running your first performance test, and understanding the results.
-## Step 1: Deploy the Infrastructure
+## Step 1: Install the Tools and the CLI
-If you haven't already deployed the cluster, run:
+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:
```bash
-make all
+brew install kind kubectl helm bmscomp/tap/kates
+kates version
```
-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.
+For 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.
-`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 ` 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:
+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:
```bash
-make status
+curl -fsSL https://raw.githubusercontent.com/bmscomp/kates/main/scripts/install-kates.sh | bash
```
-Expected output: all pods across `kafka`, `monitoring`, and `litmus` namespaces should be `Running`.
+You 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](../../README.md#building-from-source) covers it.
-## Step 2: Deploy Kates
+## Step 2: Deploy the Stack
```bash
-make kates
+kates deploy --topology isolated
```
-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.
+With no cluster reachable, `kates deploy` offers to create [`panda`](../book/appendix-a-glossary.md#gl-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.
+
+`--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 ` below needs changing.
-Verify:
+> [!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:
```bash
+kubectl get pods -n kafka
kubectl get pods -n kates
```
-You should see the Kates pod running.
+All pods should be `Running`. The Kates backend exposes a REST API that the CLI uses for all commands.
-## Step 3: Install and Configure the CLI
+## Step 3: Connect the CLI
```bash
-# Build and install
-make cli-install
-
-# Create a context
-kates ctx set local --url http://localhost:30083
-kates ctx use local
+kates ports
```
+`kates 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.
+
## Step 4: Verify Connectivity
```bash
diff --git a/docs/tutorials/07-kyverno-security.md b/docs/tutorials/07-kyverno-security.md
index 46435b13..1c7450e2 100644
--- a/docs/tutorials/07-kyverno-security.md
+++ b/docs/tutorials/07-kyverno-security.md
@@ -6,9 +6,8 @@ This tutorial walks you through managing Kyverno admission policies and running
Before starting this tutorial, ensure:
-- The full stack is deployed (`make all` + `make kates`)
-- The CLI is installed and configured (`make cli-install` + `kates ctx set local --url http://localhost:30083`)
-- **Kyverno** is installed in the cluster (included automatically when deploying with `make all`)
+- The CLI is installed (`brew install bmscomp/tap/kates`) and connected (`kates ports`), as in [Tutorial 1](01-getting-started.md)
+- The full stack is deployed with Kyverno (`kates deploy --topology isolated --with-kyverno`)
- Kyverno policies are enabled in the Helm values (`kyvernoPolicy.enabled=true`)
Verify Kyverno is running:
diff --git a/docs/tutorials/14-using-kates-from-an-ai-agent.md b/docs/tutorials/14-using-kates-from-an-ai-agent.md
index 140acd9e..56b162e9 100644
--- a/docs/tutorials/14-using-kates-from-an-ai-agent.md
+++ b/docs/tutorials/14-using-kates-from-an-ai-agent.md
@@ -31,7 +31,7 @@ show.
## Prerequisites
-- The stack from Tutorial 1, with the CLI installed (`make cli-install`)
+- The stack from Tutorial 1, with the CLI installed (`brew install bmscomp/tap/kates`)
- Claude Code, with `claude` on your `PATH`
- `jq`, to pick one field out of JSON
diff --git a/docs/tutorials/15-ide-authoring-and-lsp.md b/docs/tutorials/15-ide-authoring-and-lsp.md
index cc9f4619..30b8d35f 100644
--- a/docs/tutorials/15-ide-authoring-and-lsp.md
+++ b/docs/tutorials/15-ide-authoring-and-lsp.md
@@ -30,7 +30,7 @@ and running a live cluster pre-flight check against `krafter`.
## Prerequisites
-- The `kates` CLI installed on your `PATH` (`make cli-install`)
+- The `kates` CLI installed on your `PATH` (`brew install bmscomp/tap/kates`)
- Visual Studio Code (`1.85` or newer) with `code` on your `PATH`, and Node.js 22+
- Optional for Step 5: the Kind lab from Tutorial 1 with `kates ports` running
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
index 00fa5ca1..9048644f 100644
--- a/docs/tutorials/README.md
+++ b/docs/tutorials/README.md
@@ -56,9 +56,9 @@ Tutorial 1 (Getting Started)
## Prerequisites
All tutorials assume:
-- The full stack is deployed (`make all` + `make kates`)
-- The CLI is installed (`make cli-install`)
-- The CLI is configured with a context that carries the API key, as the Quick Start in [Introduction](../book/01-introduction.md#quick-start) sets it up (`kates ctx set local --url http://localhost:30083 --api-key …`)
+- The CLI is installed (`brew install bmscomp/tap/kates`), with Docker, Kind, kubectl and Helm, as [Tutorial 1](01-getting-started.md#step-1-install-the-tools-and-the-cli) sets them up
+- The full stack is deployed (`kates deploy --topology isolated`)
+- The CLI has a context that carries the API key (`kates ports` writes one)
## Resource Requirements
diff --git a/website/index.html b/website/index.html
index 307a6ca9..49a67d00 100644
--- a/website/index.html
+++ b/website/index.html
@@ -236,11 +236,10 @@ From an empty laptop to a graded load test.
kates deploy.
- - Install the CLI with Homebrew, and clone the repository for its
make targets.
- - Create the lab: a three-zone Kind cluster named
panda, with the Kates API image loaded.
- - Deploy the stack with a wizard, or
--dry-run to see the plan first. It installs into kubectl's current context, so check that first.
+ - Install the tools and the CLI with Homebrew, on macOS or Linux. No clone of the repository needed.
+ - Deploy the stack with a wizard, or
--dry-run to see the plan first. With no cluster reachable, it offers to create panda, a three-zone Kind cluster; otherwise it installs into kubectl's current context, so check that first.
- Open the ports: the CLI context is configured with the API URL and key.
- - Run a test and read the graded report. When you finish,
make clean removes the lab.
+ - Run a test and read the graded report. When you finish,
kind delete cluster --name panda removes the lab.
Full quick start
@@ -250,22 +249,16 @@
From an empty laptop to a graded load test.
Terminal
-
# 1. The CLI (macOS or Linux)
-brew install bmscomp/tap/kates
-git clone https://github.com/bmscomp/kates && cd kates
-git checkout "$(git describe --tags --abbrev=0 --match 'v*')"
+# 1. Kind, kubectl, Helm and the CLI (macOS or Linux), with Docker running
+brew install kind kubectl helm bmscomp/tap/kates
-# 2. A three-zone Kind cluster named panda
-make cluster
-make kates-native
-
-# 3. The stack: Strimzi, Kafka, monitoring, chaos, Kates API
+# 2. The stack on a new three-zone Kind cluster: Strimzi, Kafka, monitoring, chaos, Kates API
kates deploy
-# 4. Port-forwards and a ready CLI context
+# 3. Port-forwards and a ready CLI context
kates ports
-# 5. A first load test, then a CI gate (exit 1 below the grade)
+# 4. A first load test, then a CI gate (exit 1 below the grade)
kates test create --type LOAD --records 100000 --wait
kates gate --min-grade C --records 100000