Files

296 lines
11 KiB
Python
Executable File

#!/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()