docs(tls): say Grafana terminates TLS, and issue a leaf that verifies

[Gerrrt]

Closes #74.

Grafana has terminated TLS since the roadmap entry that recorded it. Three places still said otherwise.

What the issue got right, and what had moved

Two of the five places it named were already fixed — Makefile:250-256 now explains that the stale claim is how #69 happened, and README.md:198 already says "Grafana on :3000 over https". The rest are here.

The stale claim was runtime output, not just a comment

gen-certs.sh renders its own header for --help via sed -n '2,32p', so make certs ARGS=--help printed "Nothing in this repository terminates TLS yet" to the operator running the step that exists precisely because Grafana does.

That literal range had also drifted and was truncating the last paragraph mid-sentence (…how a lab ends up with one — then nothing). --help now prints the comment block bounded by where the comments stop, so it can't slip again.

The runbook's forward pointer went nowhere

generate-certificates.md said putting the rest behind TLS was "tracked in roadmap.md" — nothing tracks it. #182 is authentication of the ingest ports, #91 is TLS-expiry probing, #97 is MokerLink DNS.

Prometheus, Alertmanager and Loki genuinely are plain HTTP, so that half stays. The pointer now goes to security.md, where this is already recorded as an accepted residual with firewall default-deny as the control — describing reality rather than inventing a commitment.

A latent deploy-breaking bug, found in the same pass

prometheus.yaml:43 sets server_name: grafana and verifies that short name over the compose network. All seven documented make certs invocations omitted --dns grafana.

The running certificate carries the SAN, so nothing is broken today — but a fresh clone following the docs would mint a leaf without it, and the grafana scrape would fail with x509: certificate is valid for grafana.matrix.elysium, not grafana: one target down, for a reason that reads like a trust problem rather than a missing field. All seven now pass it, with the reason written down beside the existing --ip note.

Scheme where a reader starts

architecture.md's diagram node and ports table, and the stack's service table, now say Grafana is https and the only service that terminates TLS. docs/adr/0012 is deliberately left alone — it is a point-in-time decision record.

Verification

• The documented command now reproduces the live certificate's SANs exactly — DNS:grafana.matrix.elysium, DNS:grafana, IP Address:10.0.99.20 — issued into a scratch dir, never touching the real CA.
• make validate — all 20 checks pass, including shellcheck on the awk change and "documents agree with the configs".
• make certs ARGS=--help prints the full header, ending at …accept the prompt on every issue.
• Live stack untouched and healthy: up{job="grafana"} = 1, scraping https://grafana:3000/metrics.
• Repo-wide sweep finds no surviving "terminates TLS yet" claim in source or runtime output.

Added after review of the follow-ups

A fourth claim of the same family, in this same file, missed on the first pass because I grepped for "terminates TLS" and not for "until that exists". The Renewal section said adding blackbox-exporter for TLS-expiry checks was on roadmap.md, "until that exists".

It exists — compose.yaml:258-279 defines it, prometheus.yaml scrapes it. What does not exist is any expiry checking: it probes only the wiki over plain HTTP, nothing reads probe_ssl_earliest_cert_expiry, and Grafana is not a target, so nothing watches the one certificate this runbook exists to issue.

The consequence the paragraph warned about is still true; it was just blaming a missing component instead of unfinished work on a running one. It now points at #91, whose roadmap entry is corrected in #198.

Noticed, deliberately not fixed here

Neither belongs in a TLS-wording PR; both are worth their own issue:

• prometheus/tests/blackbox.test.yaml uses https://… instance labels while targets/blackbox.yaml defines http:// and comments that the wiki is plain HTTP. Tests pass — the label is cosmetic — but the fixtures misrepresent it.
• roadmap.md:52-54 lists "Add blackbox-exporter" as pending; it exists in compose.yaml:258-279. Only the TLS-expiry probing is actually outstanding.

🤖 Generated with Claude Code