Skip to content

feat(cli): kates deploy installs Kates standalone or under the Kates operator - #677

Merged
bmscomp merged 3 commits into
mainfrom
feat/cli-deploy-operator-mode
Nov 16, 2026
Merged

bmscomp merged 3 commits into
mainfrom
feat/cli-deploy-operator-mode

Conversation

@bmscomp

@bmscomp bmscomp commented Nov 15, 2026

Copy link
Copy Markdown
Owner

kates deploy --kates-mode standalone|operator, configurable by flag and in the wizard.

Modes

standalone (default, unchanged) operator
API the kates chart the Kates operator plus a Kates resource named kates
PostgreSQL the chart's own kates-db, the charts/cdc-postgresql chart, open to the Kates pods alone; or --kates-db-secret <Secret with url, username, password>
Members 1 --kates-replicas 1, 3 or 5
Operator namespace n/a --operator-ns (default kates-operator)

What stays the same: the Service is kates and the key is in Secret kates-api-key in both modes, so kates ports, kates health and the context key behave identically.

Wizard: asks the mode right after the components, then the members, the operator namespace and an optional database Secret.

Pieces

  • Components:
    • kates-operator and kates-db are new components in the deploy graph.
    • The Kates component applies the Kates resource with the chart's Kafka settings and chaos/topology targets. It sets replication 1 on one broker, as standalone does.
    • pkg/components lists both new releases and the Kates CRD group, so the plan, kates clean (resources deleted while the operator still runs, operator uninstalled last) and kates deploy status cover them.
  • Secrets:
    • The API key and database passwords are kept across runs.
    • Helm gets passwords through a 0600 values file, removed afterwards, and kubectl on stdin. They never appear on a command line, so --verbose can't print them.
  • Guards:
    • Mode switch: operator mode over a standalone install is refused, and the reverse too.
    • Admin-less: operator mode with --adminless is refused.
    • Flag combinations: --kates-replicas/--kates-db-secret without operator mode are refused, and replicas other than 1/3/5.
    • Readiness: a Kates resource that isn't Ready makes deploy print the operator's reason, not a bare timeout.
  • Published charts:
    • release.yml adds operator/chart to ChartVersions.
    • Deploy pulls kates-operator only in operator mode, including when the wizard picks it after the first pull.
    • It verifies that chart against publish-operator.yml@refs/tags/operator-v*.
    • publish-operator.yml now attests the chart's provenance, which deploy requires. The first operator release with the attestation (0.3.0) must come before the Kates release whose CLI pulls it.
  • Docs: CLI reference rows and "Standalone or Under the Operator" in the deployment chapter.

Proof

Unit tests:

  • New: mode validation; selection and chart dirs; the Kates manifest; kates-db keeps its password and never puts it on the command line; the Kates install with an existing key and --kates-db-secret; a missing DB Secret named; the mode-switch guard; the per-chart signer; the not-Ready reason.
  • Updated fixtures: the table invariants, the fake ChartVersions and the mirror table.
  • Results: go test ./... green. golangci-lint shows only the two existing mcp_test.go errcheck findings.

On a fresh three-node Kind cluster:

  • Dry run: lists the Kates Operator, PostgreSQL (Kates) and Kates Backend, plus the operator namespace.
  • Real run: the operator was installed in kates-operator, watching kates. kates-db came up, and the Kates resource was applied with 3 members, spread over 3 nodes.
  • Bugs that run found, fixed here:
    • Operator namespace: deploy drops Helm's --create-namespace, so that namespace is now on deploy's namespace list.
    • Bare timeout: the not-Ready wait now names the reason.

Not proven end to end:

  • No leader: the run reached the members but not a Ready quorum. Deploy picked this Mac's leftover kates:native-local image (2026-10-25, before the quorum existed), so no leader could be elected.
  • Docker stopped: pointing the resource at a quorum image deadlocked the operator's roll (below), and while I recreated the members by hand, Docker stopped on this machine.
  • Single member: a run with --kates-replicas 1 wasn't done.

Known, outside this PR:

  • Kind taint: a fresh Kind from config/cluster.yaml keeps the control-plane taint, which leaves two Kafka pods Pending in any mode.
  • Image skew: until operator 0.3.0 is published, a checkout deploy pairs the post-O3b chart with the 0.2.0 image, and its CRD hook fails (403 on katestests).
  • Roll deadlock: a quorum that never elected a leader can't be rolled to another version: the roll waits for a leader.

…operator

--kates-mode picks how deploy installs the Kates API:

- standalone (default, unchanged): the kates chart with its own PostgreSQL.
- operator: the Kates operator (operator/chart, or the published
  kates-operator chart), a PostgreSQL for Kates (the kates-db release of
  charts/cdc-postgresql, open to the Kates pods alone, or an existing Secret
  named by --kates-db-secret), and a Kates resource named kates that the
  operator runs as one member or, with --kates-replicas 3 or 5, a quorum.

The Service stays kates and the key stays in Secret kates-api-key, so kates
ports, health and the context key work in either mode. --operator-ns places
the operator (a scope flag, so clean and status take it too). The wizard asks
the mode after the components, then the members, namespace and database.
Passwords go to Helm through a 0600 values file and to kubectl on stdin, never
on a command line. Deploy refuses to install one mode over the other, and
refuses operator mode with --adminless. When the Kates resource does not get
Ready it prints the operator's reason.

The component table gains kates-operator, kates-db and the Kates CRD group, so
the plan, clean and status cover them; clean deletes the Kates resource while
the operator still runs. Release builds now carry the kates-operator chart
version, deploy checks that chart against publish-operator.yml's signature,
and publish-operator.yml attests the chart's build provenance.
@bmscomp

bmscomp commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

The live run on the three-node Kind cluster is now finished, picking up from the description's "Not proven" section:

  • Quorum Ready: the Kates resource deploy applied, with its 3 members, became Ready with leader kates-2 once it ran a quorum image. Getting there needed the operator fix in fix(operator): a quorum whose members cannot run one is rolled all at once #678: members that crash or run a pre-quorum image are now rolled together.
  • kates deploy status: "Kates Operator" healthy (2/2), "PostgreSQL (Kates)" healthy (1/1), and "Kates Backend" shown as helm=operator, healthy 3/3.
  • API key: the key in Secret kates-api-key works through Service kates: /api/tests answers 200 with it and 401 without.
  • kates clean --yes: removed the Kates resources first (step 1), then uninstalled kates-db, kates-operator and Strimzi, deleted the namespaces, and removed the kates.kates.io CRD. Nothing was left.

Still not run: --kates-replicas 1, and a deploy rerun that picks a quorum image by itself. Deploy's kind image detection preferred an older local kates:native-local on that machine.

aScheduledRunStoresItsReportOnce evaluated an every-minute schedule at
now + 61 s and 10 s later. With now past second 49, the second tick fell in
the next minute, whose due time rightly ran too: "execute wanted 1 time, was
2", about one run in six. Both ticks now sit in the minute after now's.
@bmscomp
bmscomp merged commit 07b7569 into main Nov 16, 2026
69 checks passed
bmscomp added a commit that referenced this pull request Nov 16, 2026
Chart and appVersion 0.3.0, and the README's install, verify and pull
commands on it. The chart description drops the run kinds 0.3.0 removes
(#675), and the CronJob example pins kates-tester 1.41.0.

0.2.0 was published before publish-operator.yml attested the chart (#677),
so kates deploy --kates-mode operator refuses it; 0.3.0 is pushed, signed
and attested.
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