docs(developer-manual): write the development guideline - #41
Merged
Conversation
Both files were "# 开发指南 / TODO" — a placeholder, and one of the two cases where Chinese prose sat in the English tree. The English page is now English, which also clears half of the inconsistency AGENTS.md warns about. Content is taken from the operator repositories rather than written from memory: zookeeper-operator's Makefile for the task list and the chainsaw setup, its go.mod and layout for the toolchain and structure, and operator-go's commons API for the shared-types guidance. Covers the multi-repository shape of the project, prerequisites and why the Makefile-downloaded tools should not be installed globally, the Kubebuilder layout, the development loop, and the split between envtest unit tests and chainsaw e2e on kind. Three things worth writing down because they are easy to get wrong: Generated output is committed, so `make manifests generate` producing a diff means that diff belongs in the commit. The Helm chart keeps its own copy of the CRDs and RBAC and does not update itself — helm-crd-sync and helm-rbac-sync exist, and skipping them is the usual cause of a chart installing an operator against a stale CRD. A +kubebuilder:default on a field inside `config` breaks the role to role group fold: structural defaulting fills the leaf as soon as the enclosing object exists, so "unset" stops being distinguishable from the default and the role's value can never win. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2 tasks
whg517
added a commit
that referenced
this pull request
Aug 27, 2026
… a version claim (#43) * docs(user-manual): write the Kubernetes environment page Replaces a one-line placeholder. The supported-version table comes from the chainsaw job's matrix in each operator's test.yml and release.yml, which is consistent across repositories: 1.33.7, 1.34.3, 1.35.0. The cluster requirements come from what the built-in operators actually install. secret-operator and listener-operator are CSI drivers, not ordinary controllers — they register CSIDriver objects and run node DaemonSets that mount the kubelet directory, so a cluster that forbids that cannot run them, and without them no product cluster gets secrets or service exposure. Calls out the kubelet directory explicitly. The chart defaults kubeletDir to /var/lib/kubelet and its own values.yaml notes the path varies on microk8s; when it is wrong the driver never registers and every pod wanting a secret volume sits in Pending with nothing obviously broken. Includes the command to find the real path. Also notes that the charts declare no kubeVersion constraint, so the version table is a statement of what is tested rather than something the tooling enforces. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: correct the Kubernetes version claim in two pages #41 and #42 both stated a 1.29 floor. That number came from a comment next to KIND_K8S_VERSION in zookeeper-operator's Makefile, which is the default for a locally created kind cluster — not the project's tested range, and not even consistent across repositories: zookeeper-operator defaults to 1.36.1 while hdfs, trino, secret, listener and commons all default to 1.26.15. What CI actually exercises is a matrix in the chainsaw job, identical in every operator: 1.33.7, 1.34.3 and 1.35.0. The workspace-level notes say 1.26+, which is a third answer again. Point both pages at the new Kubernetes page instead of restating a number, and note in the development guideline that KIND_K8S_VERSION is a local default CI overrides, so the next reader does not draw the same wrong conclusion from it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
One page, both language trees. Both were
# 开发指南 / TODO— a placeholder, and one of the two cases where Chinese prose sat in the English tree. The English page is now actually English, which clears half of the inconsistencyAGENTS.mdwarns about.Content is taken from the operator repositories rather than written from memory:
zookeeper-operator'sMakefilefor the task list and the chainsaw setup, itsgo.modand directory layout for the toolchain and structure, andoperator-go's commons API for the shared-types guidance.What it covers
operator-go, one repo per product, the three built-in operators, containers, chartscontroller-gen,kustomize,setup-envtest,golangci-lint,chainsaw) should not be installed globallysetup-chainsaw-clusterinstallscommons-operator/listener-operator/secret-operatorfirstoperator-gowith areplacedirective, and removing it before the PRThree things worth writing down
Generated output is committed.
make manifests generateproducing a diff means that diff belongs in the commit — CI will otherwise show it.The Helm chart keeps its own copy of the CRDs and RBAC and does not update itself.
make helm-crd-syncandmake helm-rbac-syncexist for this, and skipping them is the usual cause of a chart installing an operator against a stale CRD.A
+kubebuilder:defaulton a field insideconfigbreaks the role to role group fold. Structural defaulting fills the leaf as soon as the enclosing object exists, so "unset" stops being distinguishable from the default and the role's value can never win. Several fields in the framework carry comments explaining exactly this; the guideline now warns about it up front.Testing
npm run verifyexits 0 — 52 files linted with 0 errors, both locales builtonBrokenLinks: 'throw'would have failed the buildRemaining stage 2 placeholders
6 left:
kubernetes,kubebuilder,spark-k8s-operator,faq,release-notes, anddatabase(blocked — no operator consumes the CRD, see #38).faqandrelease-notesstill cannot be derived from source — one needs real user questions, the other release history. Those need maintainer input.Also still open from
AGENTS.md's known-inconsistency note:docs/developer-manual/first-commiter.mdremains Chinese in the English tree, and is byte-identical to itszhcounterpart. Worth a follow-up PR of the same shape as this one.🤖 Generated with Claude Code