docs, internal/chart, hack, .github: the install page is a how-to guide; its values, flags, metrics and RBAC are a reference page #18

Merged

mikluko merged 2 commits from mikluko/octant/2369-install-howto-and-reference into main

2026-10-04 12:10:57 +00:00

mikluko commented

2026-10-04 12:00:55 +00:00

(Migrated from github.com)

Ticket 2369 on map 2366. docs/content/docs/install.md keeps its address and is a how-to guide; its tables and the facts around them are one new reference page, docs/content/docs/reference/chart.md ("Chart and controller flags"). One page, not two: the flags, the RBAC and the metrics endpoints are all described in terms of the values that set them, so a split would cross-link on every row.

Before and after:

Install. Each release publishes the chart at oci://…, with the release's version as both its version and appVersion, and the three images at …, which the published chart pins by digest; a controller's image.tag set to another tag pulls that tag, unpinned.

is now a numbered step with the command, the subset fork and the helm test check with its output; the publication facts are "Published chart and images" in the reference.

cluster.tolerations: Its pod's tolerations; set, they replace tolerations whole.

is now "Tolerations of the pod. When set, they replace the whole of tolerations.", under "Values under cluster". The values table is split by the top-level key of values.yaml.

What following the page on a kind cluster changed (Helm v4.3.0, Kubernetes 1.37, published charts 0.1.1 and 0.2.0; uninstall also against the tree's chart):

helm test straight after helm install prints wget: can't connect to remote host lines before each ok; the step now shows the expected output and says so.
Upgrade is four steps (pull, apply CRDs, upgrade, test), run 0.1.1 to 0.2.0. A helm upgrade without the CRD step left the CRD at generation 1, as the page says.
Uninstall is ordered: delete the kinds with finalizers first, helm uninstall, delete the CRDs, delete the release namespace. A NatsCluster deleted after the uninstall did hang on cluster.nats.mikluko.io/jetstream-data until a controller was installed again. kubectl delete namespace nats-operator is a command the old page did not have; it removes the helm test Pods and Services and the Leases the old page listed as left behind.
Not on the page, for the record: with Helm 4, helm install on a Kubernetes cluster whose CRDs another field manager applied fails with a server-side apply conflict on .spec.versions. The page's sequence (uninstall, delete CRDs, install) does not meet it.

Anchors. On the install page #install, #upgrade and #uninstall are kept; #prerequisites is now #before-you-begin; #values, #controller-flags, #metrics, #rbac and the four RBAC subsections moved to reference/chart under the same fragments. The one inbound fragment link, story 12's install#metrics, now points at reference/chart#metrics and reference/chart#network-policy. No link from README.md, the chart's README or SECURITY.md carried a fragment into the install page; the first two now also link the new page.

What follows the tables: internal/chart/installpage_test.go is chartpage_test.go and reads the new page; Renovate's manager for the helm test image defaults matches docs/content/docs/reference/chart.md; the busybox count message in hack/release_test.go names it.

Not verified by running: the server-restart paragraph under Upgrade and the two "After you install" sections are the old page's statements, reworded.

just site-check, go test ./hack/... ./internal/e2e/... ./internal/chart/, just verify and just test pass.

Ticket 2369 on map 2366. `docs/content/docs/install.md` keeps its address and is a how-to guide; its tables and the facts around them are one new reference page, `docs/content/docs/reference/chart.md` ("Chart and controller flags"). One page, not two: the flags, the RBAC and the metrics endpoints are all described in terms of the values that set them, so a split would cross-link on every row. Before and after: > **Install.** Each release publishes the chart at `oci://…`, with the release's version as both its `version` and `appVersion`, and the three images at `…`, which the published chart pins by digest; a controller's `image.tag` set to another tag pulls that tag, unpinned. is now a numbered step with the command, the subset fork and the `helm test` check with its output; the publication facts are "Published chart and images" in the reference. > `cluster.tolerations`: Its pod's tolerations; set, they replace `tolerations` whole. is now "Tolerations of the pod. When set, they replace the whole of `tolerations`.", under "Values under `cluster`". The values table is split by the top-level key of `values.yaml`. What following the page on a kind cluster changed (Helm v4.3.0, Kubernetes 1.37, published charts 0.1.1 and 0.2.0; uninstall also against the tree's chart): - `helm test` straight after `helm install` prints `wget: can't connect to remote host` lines before each `ok`; the step now shows the expected output and says so. - Upgrade is four steps (pull, apply CRDs, upgrade, test), run 0.1.1 to 0.2.0. A `helm upgrade` without the CRD step left the CRD at generation 1, as the page says. - Uninstall is ordered: delete the kinds with finalizers first, `helm uninstall`, delete the CRDs, delete the release namespace. A `NatsCluster` deleted after the uninstall did hang on `cluster.nats.mikluko.io/jetstream-data` until a controller was installed again. `kubectl delete namespace nats-operator` is a command the old page did not have; it removes the `helm test` Pods and Services and the Leases the old page listed as left behind. - Not on the page, for the record: with Helm 4, `helm install` on a Kubernetes cluster whose CRDs another field manager applied fails with a server-side apply conflict on `.spec.versions`. The page's sequence (uninstall, delete CRDs, install) does not meet it. Anchors. On the install page `#install`, `#upgrade` and `#uninstall` are kept; `#prerequisites` is now `#before-you-begin`; `#values`, `#controller-flags`, `#metrics`, `#rbac` and the four RBAC subsections moved to `reference/chart` under the same fragments. The one inbound fragment link, story 12's `install#metrics`, now points at `reference/chart#metrics` and `reference/chart#network-policy`. No link from `README.md`, the chart's README or `SECURITY.md` carried a fragment into the install page; the first two now also link the new page. What follows the tables: `internal/chart/installpage_test.go` is `chartpage_test.go` and reads the new page; Renovate's manager for the `helm test` image defaults matches `docs/content/docs/reference/chart.md`; the busybox count message in `hack/release_test.go` names it. Not verified by running: the server-restart paragraph under Upgrade and the two "After you install" sections are the old page's statements, reworded. `just site-check`, `go test ./hack/... ./internal/e2e/... ./internal/chart/`, `just verify` and `just test` pass.