docs: the NetworkPolicy convention and its render test
Validate Helm Charts / Build teamspeak-server (pull_request) Successful in 5s
Validate Helm Charts / Build stalwart (pull_request) Successful in 5s
Validate Helm Charts / Build sure (pull_request) Successful in 7s
Validate Helm Charts / Build urlaubsverwaltung (pull_request) Successful in 6s
Validate Helm Charts / Build valkey (pull_request) Successful in 5s
Validate Helm Charts / Build template-chart (pull_request) Successful in 5s
Validate Helm Charts / Build voucher-vault (pull_request) Successful in 5s
Validate Helm Charts / Build ytdlp-web-player (pull_request) Successful in 10s
Validate Helm Charts / Build zipline (pull_request) Successful in 11s
Validate Helm Charts / Trivy config bentopdf (pull_request) Successful in 16s
Validate Helm Charts / Trivy config bulwark (pull_request) Successful in 12s
Validate Helm Charts / Trivy config calibre-web-automated (pull_request) Successful in 12s
Validate Helm Charts / Trivy config cyberchef (pull_request) Successful in 20s
Validate Helm Charts / Trivy config freesailarr (pull_request) Successful in 14s
Validate Helm Charts / Trivy config garage (pull_request) Successful in 16s
Validate Helm Charts / Trivy config homeassistant (pull_request) Successful in 12s
Validate Helm Charts / Trivy config keycloak (pull_request) Successful in 14s
Validate Helm Charts / Trivy config minecraft-router (pull_request) Successful in 26s
Validate Helm Charts / Trivy config gotenberg (pull_request) Successful in 12s
Validate Helm Charts / Trivy config matrix-synapse (pull_request) Successful in 26s
Validate Helm Charts / Trivy config minecraft-server (pull_request) Successful in 12s
Validate Helm Charts / Trivy config outline (pull_request) Successful in 12s
Validate Helm Charts / Trivy config paperless-ngx (pull_request) Successful in 16s
Validate Helm Charts / Trivy config patchmon (pull_request) Successful in 12s
Validate Helm Charts / Trivy config rallly (pull_request) Successful in 12s
Validate Helm Charts / Trivy config samba (pull_request) Successful in 20s
Validate Helm Charts / Trivy config satisfactory (pull_request) Successful in 15s
Validate Helm Charts / Trivy config rss-bridge (pull_request) Successful in 14s
Validate Helm Charts / Trivy config searxng (pull_request) Successful in 12s
Validate Helm Charts / Trivy config sure (pull_request) Successful in 12s
Validate Helm Charts / Trivy config teamspeak-server (pull_request) Successful in 30s
Validate Helm Charts / Trivy config voucher-vault (pull_request) Successful in 12s
Validate Helm Charts / Trivy config ytdlp-web-player (pull_request) Successful in 16s
Validate Helm Charts / Trivy config stalwart (pull_request) Successful in 13s
Validate Helm Charts / Trivy config template-chart (pull_request) Successful in 17s
Validate Helm Charts / Detect changed charts (pull_request) Successful in 4s
Validate Helm Charts / Trivy config urlaubsverwaltung (pull_request) Successful in 13s
Validate Helm Charts / Trivy config valkey (pull_request) Successful in 11s
Validate Helm Charts / Trivy config zipline (pull_request) Successful in 13s
Validate Helm Charts / Selector match (pull_request) Successful in 9s
Validate Helm Charts / NetworkPolicy (pull_request) Successful in 13s
Validate Helm Charts / Trivy config apache-tika (pull_request) Successful in 12s
Validate Helm Charts / Resource quantities (pull_request) Successful in 13s
Validate Helm Charts / HTTPRoute match (pull_request) Successful in 9s
Validate Helm Charts / Bump level (pull_request) Successful in 4s
Validate Helm Charts / YAML scalars (pull_request) Successful in 19s
Validate Helm Charts / Build apache-tika (pull_request) Successful in 5s
Validate Helm Charts / Build bentopdf (pull_request) Successful in 6s
Validate Helm Charts / Build cyberchef (pull_request) Successful in 8s
Validate Helm Charts / Build freesailarr (pull_request) Successful in 6s
Validate Helm Charts / Build gotenberg (pull_request) Successful in 10s
Validate Helm Charts / Build homeassistant (pull_request) Successful in 9s
Validate Helm Charts / Build bulwark (pull_request) Successful in 9s
Validate Helm Charts / Build calibre-web-automated (pull_request) Successful in 11s
Validate Helm Charts / Build garage (pull_request) Successful in 9s
Validate Helm Charts / Build keycloak (pull_request) Successful in 5s
Validate Helm Charts / Build matrix-synapse (pull_request) Successful in 4s
Validate Helm Charts / Build minecraft-router (pull_request) Successful in 6s
Validate Helm Charts / Build minecraft-server (pull_request) Successful in 7s
Validate Helm Charts / Build outline (pull_request) Successful in 5s
Validate Helm Charts / Build patchmon (pull_request) Successful in 5s
Validate Helm Charts / Build rallly (pull_request) Successful in 5s
Validate Helm Charts / Build paperless-ngx (pull_request) Successful in 6s
Validate Helm Charts / Build satisfactory (pull_request) Successful in 16s
Validate Helm Charts / Build rss-bridge (pull_request) Successful in 5s
Validate Helm Charts / Build samba (pull_request) Successful in 12s
Validate Helm Charts / Build searxng (pull_request) Successful in 6s
Install-test / Install-test apache-tika (pull_request) Successful in 1m9s
Install-test / Install-test bentopdf (pull_request) Successful in 53s
Install-test / Install-test bulwark (pull_request) Successful in 1m18s
Install-test / Install-test calibre-web-automated (pull_request) Successful in 1m47s
Install-test / Install-test cyberchef (pull_request) Successful in 51s
Install-test / Install-test freesailarr (pull_request) Successful in 3m28s
Install-test / Install-test garage (pull_request) Successful in 1m8s
Install-test / Install-test gotenberg (pull_request) Successful in 1m12s
Install-test / Install-test homeassistant (pull_request) Successful in 2m20s
Install-test / Install-test minecraft-router (pull_request) Successful in 40s
Install-test / Install-test outline (pull_request) Successful in 2m15s
Install-test / Install-test keycloak (pull_request) Successful in 1m54s
Install-test / Install-test matrix-synapse (pull_request) Successful in 1m12s
Install-test / Install-test minecraft-server (pull_request) Successful in 1m45s
Install-test / Install-test paperless-ngx (pull_request) Successful in 3m15s
Install-test / Install-test patchmon (pull_request) Successful in 1m23s
Install-test / Install-test rallly (pull_request) Successful in 1m44s
Install-test / Install-test rss-bridge (pull_request) Successful in 46s
Install-test / Install-test samba (pull_request) Successful in 1m9s
Install-test / Install-test searxng (pull_request) Successful in 1m5s
Install-test / Install-test stalwart (pull_request) Successful in 1m18s
Install-test / Install-test sure (pull_request) Successful in 2m26s
Install-test / Install-test teamspeak-server (pull_request) Successful in 1m14s
Install-test / Install-test urlaubsverwaltung (pull_request) Successful in 1m37s
Install-test / Install-test valkey (pull_request) Successful in 1m14s
Install-test / Install-test voucher-vault (pull_request) Successful in 1m49s
Validate Helm Charts / Install-test (pull_request) Successful in 43m53s
Install-test / Install-test ytdlp-web-player (pull_request) Successful in 59s
Install-test / Install-test zipline (pull_request) Successful in 1m51s

README gains two sections and CLAUDE.md the binding compact summary.

"NetworkPolicies (#5)" under Chart style guidelines carries the part that is
actually hard to get right: the FOUR PORT CLASSES, and that the class decides
the rule. A port a network probe addresses stays open until probeSources is
set, because the kubelet probes from the worker node's IP and no chart can know
it. A NodePort-published port stays open because the source is already
masqueraded. Everything else can be - and is - restricted by source, which is
why the charts with a real inbound restriction are exactly the ones whose
probes use a different port: keycloak's 8080, garage's s3 and web,
minecraft-server's RCON, teamspeak-server's query interface. And a cluster bus
between a release's own replicas gets a bare podSelector, with the reminder
that policyTypes Egress means the outbound side needs its own rule or the
cluster never forms while every node looks healthy.

The exec-probe distinction is written down as load-bearing rather than
pedantic, because it is the whole reason valkey and minecraft-server are the
tightest policies here and every HTTP-probed web app is looser.

What the policies do NOT do has its own list, including the two that will
surprise someone: most dependency ports are the STANDARD ones rather than the
configured ones, because connection details live in 1Password items the charts
never parse - with keycloak, stalwart and minecraft-router named as the
exceptions that derive theirs from values; and a subchart's pods are not
covered, with ytdlp-web-player's oauth2-proxy as the sharp case and
paperless-ngx' valkey as the opposite.

The three Ingress-only charts are listed with their individual arguments rather
than a blanket excuse, and gotenberg is contrasted against them: it keeps a
DNS-only cap on purpose, because it drives a headless Chromium on a port the
whole cluster can reach.

"NetworkPolicy render test" under CI/CD documents the gate, and ends with what
the pipeline cannot prove - including the measurement from this PR that k3s
exempts kubelet probe traffic from policy, so the install-test's net is an
EGRESS net. That is stated there rather than implied, because it is the reason
assertion 2 matters: a wrong ingress port is caught mechanically or not at all.

Part of #5
This commit is contained in:
jklein committed 2026-10-14 14:48:21 +00:00
1 parent 73c2ec704f
commit 8233617f57
2 files changed
+81

No files matched your search

+1
View File
@@ -116,6 +116,7 @@ The binding style guide for all current and future charts lives in **README.md (
- Every container offers an additive `env` block rendered through `tpl` with `value`, `secretKeyRef`, and `configMapKeyRef` forms.
- Hardening: `automountServiceAccountToken: false`, non-root, `readOnlyRootFilesystem: true`, caps dropped, `allowPrivilegeEscalation: false`; contexts values-configurable (`securityContext.pod` / `securityContext.container`); writable paths as emptyDirs; image-forced deviations MUST be documented with a comment in the chart's `values.yaml`.
- Probes: liveness/readiness/startup on every workload (exception: paperless consume CronJob), values-configurable with calibrated defaults.
- **Every chart renders a `NetworkPolicy`, `networkPolicy.enabled` defaults to `true`** (#5); adding one to an existing chart is a **major**. Values: `enabled`, `allowedNamespaces`, `probeSources`, `ingressController`, `egress.extraPorts` — and only the ones that actually reach a rule, because a value that does nothing reads as a control. Each port falls in one of four classes and the class decides the rule: a port a **network** probe addresses stays open (`no from`) until `probeSources` is set, because the kubelet probes from the worker node's IP and no chart can know it; a NodePort-published port stays open (the source is already masqueraded); anything else is restricted to the namespace, `allowedNamespaces` and — for HTTP — `ingressController`; a replica-to-replica bus gets a bare `podSelector`. **`exec` probes are not network probes** (no packet, so the port can be restricted — `valkey`, `minecraft-server`). **Pod ports, never NodePorts.** Never `from: []`. Reasoning in Go template comments, never `#` (those ship to the cluster), and such a comment must not spell out its own closing delimiter. Egress is by **port, never destination** — Canal has no FQDN rule and Calico-specific objects are out of scope — so most dependency ports are the *standard* ones and a dependency elsewhere is blocked; `policyTypes` names only what there is something to restrict (`valkey`, `homeassistant`, `satisfactory` are Ingress-only, each argued in its own file). `ci/run-networkpolicy-test.sh` is the gate. Full rules: README, "NetworkPolicies".
- Resources: requests as values defaults; limits auto-computed by the `_helpers.tpl` helper (`limitFactor` default 3; no CPU limits unless set explicitly).
- Replicas per workload (explicit `0` allowed) plus a chart-global `scaleDown` flag that overrides them.
- `icon:` mandatory in every `Chart.yaml`; `helm lint --strict` without findings; CI fixtures under `ci/<chart>/` or a justified exclusion.