Docs pages generated from the chart: values, ports and policies, alerts (K-D2) #30
No files matched your search
@@ -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,2 +1,3 @@
|
||||
# Tools from tools/install-tools.sh
|
||||
.tools/
|
||||
__pycache__/
|
||||
@@ -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
File diff suppressed because it is too large.
Load diff
@@ -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
|
||||
@@ -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.
|
||||
|
||||
Executable
+295
@@ -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
@@ -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():
|
||||
|
||||
Reference in new issue
Block a user