[bmscomp]

Why

After #439 and #441 there are two ways to install Kates. A cluster admin installs it cluster-wide with chaos, and a team with only edit installs it in its own namespace (rbac.scope=namespace). The book covered CI only in pieces: test apply --wait in Scenario Files, --fail-on-sla-breach in Chaos Practice, --output-junit in Conformity Checks. Nothing said how a runner reaches the API under either install, or which gates each install can run.

What changes

docs/book/14-recipes.md gains Recipe 7: Gate a CI Pipeline on Kafka, plus its row in the recipes table, an intro bullet and a Summary bullet. The recipe covers:

• Which gates each install mode can run: scenario gates, kates gate, the conformity check, and the chaos SLA, which needs a cluster-wide install with a chaos provider.

• Reaching the API:

  • an in-cluster runner uses the Service URL;
  • an outside runner goes through an Ingress, or through kubectl port-forward, which edit allows.

  The chart's NetworkPolicy admits port 8080 from any namespace.

• The API key: from the kates-api-key Secret, or your own Secret via apiKey.existingSecret. The CLI reads KATES_URL and KATES_API_KEY ahead of any context, so the runner needs no config file.

• A scenario file with LOAD and INTEGRITY gates, and every gate command's exit codes.

• A GitHub Actions workflow:

  • installs a pinned CLI and verifies it against the release's checksums.txt;
  • port-forwards to the API, runs each gate as its own step, and uploads the JUnit reports;
  • runs the chaos gate only when the repository variable KATES_CHAOS is true.

• Limits:

  • no chaos under namespace scope;
  • conformity rules that come back UNKNOWN there;
  • the conformity check needs a 1.27.0+ API;
  • a cancelled job leaves a disruption plan running.

Evidence

• Live on panda, with only KATES_URL and KATES_API_KEY set and no CLI config:
  • kates test apply -f kafka-gates.yaml --wait -o json exited 1: LOAD broke p99=1484ms > 500ms, while INTEGRITY met all three integrity gates.
  • kates report export <id> --format junit wrote JUnit for both runs.
  • kates gate --min-grade C exited 1, with grade F on the Kind lab.
  • The lab's older native image answered the conformity check with a 404, and the CLI exited 2, which the Limits section describes. The conformity check itself was verified on 1.27.0+ in feat(chart,conformity): rbac.scope=namespace runs tests and conformity checks without cluster admin #439.
• actionlint passes on the recipe's workflow.
• Format check: checksums.txt is the concatenated shasum -a 256 lines (release.yml), which the install step's grep | sha256sum -c matches.
• Fact-check: four checkers went through every claim, each followed by a skeptic that tried to refute what it reported. Five findings survived, all fixed in this PR:
  • --fail-on-sla-breach exits 0 for a plan without an sla block, or one that ends PARTIAL or FAILED, so the recipe says to give the plan an sla;
  • exec in the test step, so cancelling the job reaches kates and cancels the run;
  • a chaos gate needs a chaos provider;
  • monitoring.podMonitor can also be UNKNOWN under namespace scope;
  • the "two recipes disrupt" count in the intro was stale.
• Book: check-book-style.sh passes, the metrics ratchet doesn't rise, and a scratch Quarto render shows no warnings.

Not done

• The workflow hasn't run on GitHub itself. The recipe's step that keeps a port-forward running from one step into the next relies on documented GitHub Actions behaviour, and I haven't tried it.
• The chaos gate wasn't run live, because it disrupts the lab. Its exit codes come from cli/cmd/disruption.go and the Kates API's orchestrator.