Skip to content

docs: explain the Kates operator mode, and that standalone is unchanged - #686

Merged
bmscomp merged 1 commit into
mainfrom
docs/kates-operator-mode
Nov 17, 2026
Merged

bmscomp merged 1 commit into
mainfrom
docs/kates-operator-mode

Conversation

@bmscomp

@bmscomp bmscomp commented Nov 17, 2026

Copy link
Copy Markdown
Owner

What

  • Book: a new chapter, Running Kates Under the Kates Operator, in Part V right after the Deployment Guide. It covers the two modes, what stays the same in standalone, deploying with --kates-mode operator, the Kates resource's conditions, the quorum and failover, drained upgrades, a lost node, a lost majority, a Helm install, switching modes and the limits.
  • Tutorial 16: Running Kates Under the Kates Operator, on panda. It deploys three members, reads the resource, uses the same CLI, kills the leader, drains, loses a node and switches back.
  • Pointers to both from the Deployment Guide (section and handoff), the Upgrade Playbook, the Part V page, the glossary (gl-kates-operator), the concept registry, the book README, tutorials 1 and 8, the tutorials index and the README.

Compatibility claims, and where they come from

  • Standalone is the default: --kates-mode defaults to standalone (cli/cmd/deploy.go:142).
  • The quorum is off unless kates.quorum.peers is set (kates/src/main/resources/application.properties:482), and only the operator sets it. A standalone /api/health shows "quorum":{"enabled":false} (Quorum.health()).
  • Deploy refuses to install one mode over the other, and refuses operator-only flags in standalone mode (cli/cmd/deploy_kates_operator.go).
  • The one break applies only to early operator users: KatesTest and KafkaCompliance were removed (feat(operator)!: remove KatesTest and KafkaCompliance #675). The chapter says so and links the chart README's upgrade steps.

Tests

  • Run locally: check-book-style.sh, book_metrics.py (new page at zero), gen-book-index.py --check (index regenerated), gen-chart-table.sh --check, a relative-link and fragment check on every changed file, and a full quarto render --to html in a scratch copy with check-book-fragments.py (all fragment links land).
  • The kubectl get kates, pods, Services and health outputs are captured from panda running v1.41.2 with three members.
  • Not run: the leader kill (step 4), drain (step 5), lost node (step 6) and switch back (step 7). Those tutorial steps describe the documented behaviour and show no captured output. lychee isn't installed locally.

Worth a look

Going back from operator mode to standalone without kates clean likely trips Helm. installKatesResource creates kates-api-key with kubectl apply, without Helm ownership labels, so helm install kates should refuse to adopt it. The tutorial and chapter tell you to delete that Secret first. This is from reading the code, not from a run.

A new book chapter, Running Kates Under the Kates Operator, after the
Deployment Guide: the two modes side by side, what stays the same in the
default standalone mode (the quorum is off unless the operator configures
peers; the drain switch and the health quorum block are additions), the one
change for early operator users (KatesTest and KafkaCompliance), deploying
with --kates-mode operator, the Kates resource's conditions, the quorum and
its failover, drained upgrades, a lost node, a lost majority, a Helm install,
switching modes and the limits. Outputs are from panda.

Tutorial 16 runs the quorum on panda: deploy, read the resource, use the same
CLI, kill the leader, drain, lose a node, switch back.

The Deployment Guide, Upgrade Playbook, Part V page, glossary, concept
registry, book README, tutorials 1 and 8, the tutorials index and the README
point to both.
@bmscomp
bmscomp merged commit 68e090f into main Nov 17, 2026
65 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant