crdfields

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