296 lines
11 KiB
Python
Executable File
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()
|