Documentation
¶
Overview ¶
Command crdfields renders the settings index in docs/configuration.md from the CRD schemas in config/crd/bases, so the table cannot drift from the API.
The index is the one place a reader looks to answer "what can I set, and what happens if I don't". Hand-maintaining it went wrong three times in the commit that introduced it: spec.accessFrom omitted DENIES every namespace rather than admitting them, an omitted spec.serializeNamespace INFERS per document rather than meaning false, and qps/burst fall back to operator-wide flags and are ignored without a kubeConfig. Each was written from memory of the prose and each was wrong in the direction that costs a reader an outage.
So the two halves are split by who can be trusted with them:
The SCHEMA owns whether a field is required and what it defaults to. Those come from config/crd/bases, which controller-gen regenerates from the Go types, so they cannot be stale without `task manifests` being stale too.
fields.yaml owns the one-line description and the link to the section that explains the field. Prose is not derivable: a CRD description is written for `kubectl explain` and runs to paragraphs, which is the wrong shape for a table and the wrong voice for a guide.
What makes it a gate rather than a convenience is the coverage check. Adding a field to the API and not describing it fails the build, and so does describing one that no longer exists, and so does a whole CRD kind that fields.yaml never mentions. The tool cannot write the sentence for you; it can refuse to let the table pretend the field is not there.
Depth is decided by fields.yaml, not by a fixed limit. A path listed there is a leaf: the walk stops and its children are not required. A top-level property with no entry of its own must have every one of its children described, or the run fails naming it. That is what keeps `spec.commit.window` in the table while `spec.commit.message.liveTemplate` stays in its own document.
Usage:
go run ./hack/crdfields # rewrite the generated block go run ./hack/crdfields -check # fail if the block is out of date
Source Files