Docs pages generated from the chart: values, ports and policies, alerts (K-D2) #30

Merged
jcoffey-dev merged 3 commits from feat/docs-pages into main 2026-11-20 03:30:21 +00:00
8 changed files with 743 additions and 388 deletions

No files matched your search

+1 -1
View File
@@ -39,7 +39,7 @@ jobs:
run: |
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq
apt-get install -y -qq --no-install-recommends ca-certificates curl git python3-minimal >/dev/null
apt-get install -y -qq --no-install-recommends ca-certificates curl git python3-minimal python3-yaml >/dev/null
- uses: coffey-labs/actions/checkout@fab0c4d45e0162963965f1555df27b7bed5e20ec
- run: tools/install-tools.sh
- run: tools/check.sh
+1
View File
@@ -1,2 +1,3 @@
# Tools from tools/install-tools.sh
.tools/
__pycache__/
+4
View File
@@ -78,6 +78,10 @@ runs, pinned by digest.
status names the part and why. The server container keeps its last log
lines as its termination message too. Needs server 27.1-rc.33: an older
server doesn't know `--check`.
- `tools/docs-pages.py --out <dir>` writes the docs' generated Kubernetes
pages: the values reference, the Services and their ports, what each
network policy lets in and out, and the alerts, from `helm template` with
`ci/docs-values.yaml`. CI builds them, so a change that breaks one fails.
- `charts/inbuxa/VALUES.md`, every value with its default and what the
schema allows, generated from values.yaml and the schema by
`tools/values-reference.py`; CI fails when it's out of date. The schema
+363 -363
View File
File diff suppressed because it is too large. Load diff
+40
View File
@@ -0,0 +1,40 @@
# SPDX-FileCopyrightText: 2026 Coffey Labs LLC
# SPDX-License-Identifier: Apache-2.0
#
# What tools/docs-pages.py renders the docs' tables from: the defaults, plus
# the parts most installs turn on (webmail, console, metrics, backups), so
# every Service, policy and alert shows. Anything else stays at its default.
server:
dataStore:
"@type": PostgreSql
host: pg-rw.data.svc
port: 5432
database: inbuxa
authUsername: inbuxa
authSecret: {"@type": File, filePath: /etc/inbuxa/secrets/pg-password}
useTls: true
secretMounts:
- secretName: inbuxa-data
items: [{key: pg-password, path: pg-password}]
publicUrl: https://mail.example.org
backup:
enabled: true
url: s3://mail-backups/inbuxa
existingSecret: inbuxa-backup-keys
storeCheck:
quick: {enabled: true}
full: {enabled: true}
metrics:
prometheus:
enabled: true
serviceMonitor: {enabled: true}
rules: {enabled: true}
webmail:
enabled: true
image: {tag: 27.1-rc.9}
publicUrl: https://webmail.example.org
existingSecret: webmail-secrets
console:
enabled: true
image: {tag: 27.1-rc.22}
publicUrl: https://admin.example.org
+3
View File
@@ -31,6 +31,9 @@ done
step "the values reference is current (tools/values-reference.py)"
python3 tools/values-reference.py --check
step "the docs' generated Kubernetes pages build (tools/docs-pages.py)"
python3 tools/docs-pages.py --out "$OUT/docs"
step "bad values are refused before anything is applied (tools/bad-values)"
# Each file's first line names what the refusal has to mention. helm
# template, as an install renders: the schema and the templates' own checks.
+295
View File
@@ -0,0 +1,295 @@
#!/usr/bin/env python3
# SPDX-FileCopyrightText: 2026 Coffey Labs LLC
# SPDX-License-Identifier: Apache-2.0
"""The generated pages of the docs' Kubernetes section, from the chart as
built: the values reference, the ports, Services and network policies, and
the alerts. The docs' other pages are written by hand and link to these.
tools/docs-pages.py --out ../inbuxa.org/docs-site/content/docs/kubernetes
tools/docs-pages.py --check DIR fails when DIR's copies are out of date
The tables come from `helm template` with ci/docs-values.yaml (the defaults,
plus webmail, console, metrics and backups on), so they show what an
install gets, not what the templates could make. Needs helm and PyYAML.
"""
import importlib.util, json, re, subprocess, sys
from pathlib import Path
import yaml
ROOT = Path(__file__).resolve().parent.parent
CHART = ROOT / "charts" / "inbuxa"
VALUES = CHART / "ci" / "docs-values.yaml"
PAGES = ("values.md", "ports.md", "alerts.md")
spec = importlib.util.spec_from_file_location("values_reference", ROOT / "tools" / "values-reference.py")
values_reference = importlib.util.module_from_spec(spec)
spec.loader.exec_module(values_reference)
# What each port is for, by the name the chart gives it
PORTS = {
"smtp": "Mail from the internet (MX)",
"submissions": "Mail clients sending, over TLS",
"submission": "Mail clients sending, STARTTLS",
"imaps": "IMAP over TLS",
"imap": "IMAP, STARTTLS",
"pop3s": "POP3 over TLS",
"sieve": "ManageSieve (filters)",
"https": "JMAP, CalDAV, CardDAV, WebDAV, the server's web pages, ACME",
"http": "Plain HTTP inside the cluster",
}
# What each chart part runs
COMPONENT = {
"server": "the mail server",
"webmail": "the webmail",
"console": "the console",
}
# A Service's own port, where the port's name alone says too little
SERVICE_PORTS = {
"webmail": "The webmail, behind your ingress or gateway",
"console": "The console, behind your ingress or gateway",
"metrics": "Prometheus scrapes each pod's `/metrics/prometheus`",
}
LABEL_HELP = {
"inbuxa.org/serves-http": "the groups that serve HTTP",
"inbuxa.org/serves-mail": "the groups that take mail connections",
}
def render():
out = subprocess.run(
["helm", "template", "inbuxa", str(CHART), "-n", "inbuxa", "-f", str(VALUES)],
check=True, capture_output=True, text=True,
).stdout
return [d for d in yaml.safe_load_all(out) if d]
def chart_version():
chart = yaml.safe_load((CHART / "Chart.yaml").read_text())
return chart["version"], chart["appVersion"]
def front(title, description):
version, app = chart_version()
return [
"---",
f"title: {title}",
"description: >-",
f" {description}",
"---",
f"<!-- Generated by the chart's tools/docs-pages.py (chart {version},",
f" inbuxa {app}). Don't edit it here: change the chart, then run",
" the tool. -->",
"",
]
def values_page():
entries = values_reference.read_values((CHART / "values.yaml").read_text())
schema = json.loads((CHART / "values.schema.json").read_text())
lines = front(
"Values reference",
"Every value the **inbuxa** chart takes, with its default and what it allows.",
)
lines += [
"Every value the chart takes, with its default and what the chart",
"allows. A value it doesn't name is refused, as is one outside these",
"limits, before anything is applied: `helm install` and `helm upgrade`",
"stop with the value's name and what's wrong with it.",
"",
]
lines += values_reference.body(entries, schema)
return "\n".join(lines).rstrip() + "\n"
def component(labels):
return labels.get("app.kubernetes.io/component", "")
def workloads(docs):
"""[(name, pod labels)] of every Deployment"""
return [
(d["metadata"]["name"], d["spec"]["template"]["metadata"]["labels"])
for d in docs if d["kind"] == "Deployment"
]
def selects(selector, labels):
return all(labels.get(k) == v for k, v in (selector or {}).items())
def who(selector, docs):
"""The Deployments a selector picks, by name"""
names = [n for n, labels in workloads(docs) if selects(selector, labels)]
return ", ".join(f"`{n}`" for n in names) or "none"
def peer(p):
if "podSelector" in p and "namespaceSelector" not in p:
c = component(p["podSelector"].get("matchLabels", {}))
return COMPONENT.get(c, f"pods labelled {json.dumps(p['podSelector'])}") + " pods"
if "namespaceSelector" in p:
return f"namespaces matching `{json.dumps(p['namespaceSelector'])}`"
if "ipBlock" in p:
return f"`{p['ipBlock']['cidr']}`"
return json.dumps(p)
def ports_of(rule):
ports = rule.get("ports")
if not ports:
return "any port"
return ", ".join(f"{p['port']}/{p.get('protocol', 'TCP')}" for p in ports)
def rules(kind, items):
if items is None:
return [f"- {kind}: nothing (only what other policies allow)"]
if not items:
return [f"- {kind}: nothing"]
out = []
for r in items:
peers = r.get("from") or r.get("to")
where = "anywhere" if not peers else ", ".join(peer(p) for p in peers)
out.append(f"- {kind}: {ports_of(r)}, {'from' if kind == 'In' else 'to'} {where}")
return out
def ports_page(docs):
lines = front(
"Ports, Services and network policies",
"The Services the **inbuxa** chart makes, the ports on each, and what its network policies let in and out.",
)
lines += [
"What an install with the webmail, the console, metrics and backups",
"on gets. The ports are the chart's defaults; `server.listeners`",
"moves them in the pods and `server.services` changes the Services.",
"",
"## Services",
"",
]
for s in (d for d in docs if d["kind"] == "Service"):
spec = s["spec"]
kind = spec.get("type", "ClusterIP")
if spec.get("clusterIP") == "None":
kind += ", headless"
sel = {k: v for k, v in spec["selector"].items() if not k.startswith("app.kubernetes.io/") or k == "app.kubernetes.io/component"}
lines += [
f"### `{s['metadata']['name']}`",
"",
f"{kind}. Sends to {who(spec['selector'], docs)}"
+ "".join(f" ({LABEL_HELP[k]})" for k in sel if k in LABEL_HELP) + ".",
"",
"| Port | Name | Pod port | For |",
"|---|---|---|---|",
]
own = SERVICE_PORTS.get(s["metadata"]["name"].rsplit("-", 1)[-1])
for p in spec["ports"]:
use = own if own and len(spec["ports"]) == 1 else PORTS.get(p["name"], "")
lines.append(f"| {p['port']} | `{p['name']}` | `{p.get('targetPort', p['port'])}` | {use} |")
lines.append("")
lines += [
"## Network policies",
"",
"The chart denies everything to and from its pods, then allows what",
"each part needs. `networkPolicy` narrows these (who may reach HTTP,",
"who may scrape metrics, where the server may connect).",
"",
]
for p in (d for d in docs if d["kind"] == "NetworkPolicy"):
spec = p["spec"]
sel = spec["podSelector"]
c = component(sel.get("matchLabels", {}))
expr = [e for e in sel.get("matchExpressions", []) if e["key"] == "app.kubernetes.io/component"]
if expr:
pods = "the Jobs: " + ", ".join(f"`{v}`" for v in expr[0]["values"])
elif c:
pods = COMPONENT.get(c, c)
else:
pods = "every pod of the release"
lines += [f"### `{p['metadata']['name']}`", "", f"Applies to {pods}.", ""]
types = spec.get("policyTypes", [])
if "Ingress" in types:
lines += rules("In", spec.get("ingress"))
if "Egress" in types:
lines += rules("Out", spec.get("egress"))
lines.append("")
return "\n".join(lines).rstrip() + "\n"
def alerts_page(docs):
lines = front(
"Prometheus alerts",
"The alert rules the **inbuxa** chart ships for Prometheus, and what each one means.",
)
lines += [
"With `server.metrics.prometheus.rules.enabled`, the chart ships",
"these as a PrometheusRule. Thresholds are the defaults; each is a",
"value under `server.metrics.prometheus.rules`. The ones from",
"kube-state-metrics need it running, and",
"`rules.kubeStateMetrics` (on by default).",
"",
"| Alert | Severity | After | Fires when | What to do |",
"|---|---|---|---|---|",
]
for r in (d for d in docs if d["kind"] == "PrometheusRule"):
for group in r["spec"]["groups"]:
for rule in group["rules"]:
if "alert" not in rule:
continue
notes = rule.get("annotations", {})
when = words(notes.get("summary", ""))
todo = " ".join(
t for t in re.split(r"(?<=[.;])\s+", " ".join(notes.get("description", "").split()))
if "{{" not in t
)
lines.append(
f"| `{rule['alert']}` | {rule.get('labels', {}).get('severity', '')} "
f"| {rule.get('for', 'at once')} | {cell(when)} | {cell(todo)} |"
)
return "\n".join(lines).rstrip() + "\n"
def words(summary):
"""An alert's summary without Prometheus' templating: what fills each in"""
summary = summary.strip().strip('"')
summary = re.sub(r"\{\{\s*\$labels\.pod\s*\}\}", "A server pod", summary)
summary = re.sub(r"^(\w[\w ]*?) \{\{\s*\$labels\.job_name\s*\}\}", lambda m: "A " + m[1].lower() + " Job", summary)
summary = re.sub(r"\{\{\s*\$labels\.(\w+)\s*\}\}", lambda m: f"the {m[1]}", summary)
summary = re.sub(r"\{\{\s*\$value[^}]*\}\}", "N", summary)
summary = re.sub(r"\{\{[^}]*\}\}", "…", summary)
return summary[:1].upper() + summary[1:]
def cell(text):
return text.replace("|", "\\|")
def pages():
docs = render()
return {"values.md": values_page(), "ports.md": ports_page(docs), "alerts.md": alerts_page(docs)}
def main():
args = sys.argv[1:]
if len(args) != 2 or args[0] not in ("--out", "--check"):
sys.exit(__doc__)
out = Path(args[1])
built = pages()
if args[0] == "--check":
stale = [n for n, text in built.items() if not (out / n).exists() or (out / n).read_text() != text]
if stale:
sys.exit(f"out of date in {out}: {', '.join(stale)}: run tools/docs-pages.py --out {out}")
print(f"{out}: the generated pages are current")
return
out.mkdir(parents=True, exist_ok=True)
for name, text in built.items():
(out / name).write_text(text)
print(f"wrote {out / name}")
if __name__ == "__main__":
main()
+36 -24
View File
@@ -147,18 +147,26 @@ def prose(comment):
def render(entries, root):
out = [
"<!-- Generated by tools/values-reference.py from values.yaml and",
" values.schema.json. Don't edit it by hand: change those, then run",
" the tool. CI fails when this is out of date. -->",
"",
"# inbuxa chart values",
"",
"Every value the chart takes, with its default and what the values",
"schema allows. A value the schema doesn't name is refused, as is one",
"outside these limits, before anything is applied.",
"",
]
return "\n".join(HEADER + body(entries, root)).rstrip() + "\n"
HEADER = [
"<!-- Generated by tools/values-reference.py from values.yaml and",
" values.schema.json. Don't edit it by hand: change those, then run",
" the tool. CI fails when this is out of date. -->",
"",
"# inbuxa chart values",
"",
"Every value the chart takes, with its default and what the values",
"schema allows. A value the schema doesn't name is refused, as is one",
"outside these limits, before anything is applied.",
"",
]
def body(entries, root):
"""Every value's entry, as Markdown lines (the docs pages use these too)"""
out = []
for path, comment, value, block in entries:
depth = path.count(".")
s = schema_at(root, path)
@@ -176,24 +184,28 @@ def render(entries, root):
out += ["```yaml", *example, "```", ""]
continue
default = value if value not in (None, "") else None
out.append(f"- **`{path}`**" + (f" ({kind})" if kind else ""))
if default is not None:
out.append(f" Default: `{default}`.")
elif block:
out.append(" Default:")
out.append("")
out.append(" ```yaml")
# One line each for the name, the default, the limits and the
# comment: a backslash ends a line without starting a paragraph
head = f"- **`{path}`**" + (f" ({kind})" if kind else "")
rest = []
if limits:
rest.append("Allowed: " + "; ".join(limits) + ".")
if paragraph:
rest.append(paragraph)
if default is not None or not block:
lines = [head] + ([f"Default: `{default}`."] if default is not None else []) + rest
out += [" " * (i > 0) + t + ("\\" if i < len(lines) - 1 else "") for i, t in enumerate(lines)]
else:
out += [head + "\\", " Default:", "", " ```yaml"]
indent = min(len(b) - len(b.lstrip()) for b in block if b.strip())
out += [" " + b[indent:] for b in block if b.strip()]
out.append(" ```")
if limits:
out.append(" Allowed: " + "; ".join(limits) + ".")
if paragraph:
out.append(" " + paragraph)
if rest:
out += [""] + [" " + t + ("\\" if i < len(rest) - 1 else "") for i, t in enumerate(rest)]
if example:
out += ["", " ```yaml", *[" " + e for e in example], " ```"]
out.append("")
return "\n".join(out).rstrip() + "\n"
return out
def main():