paperless-ngx: Egress-Regel nennt den Service-Port 80, braucht aber die Pod-Ports 9998/3000 #136

New Issue

2026-10-15T09:55:43+02:00

jlab-bot commented

2026-10-15 09:55:43 +02:00

Die NetworkPolicy von paperless-ngx erlaubt ausgehend 80 für Tika und Gotenberg und begründet das ausdrücklich. Die Begründung ist falsch, und das hat am 15.10.2026 in jlab-cluster/cluster-config einen Ausfall verursacht: Nach dem Ausrollen von Chart 14.0.0+up3.3.1 kam Paperless nicht mehr an Tika und Gotenberg — Mail-Import, EML, HTML und Office-Dokumente fielen aus, reine PDFs und Bilder liefen weiter.

Was im Chart steht

In values.yaml am networkPolicy-Block:

NOTE WHY THAT RULE SAYS 80 AND NOT 9998/3000: an egress rule names the port on the DESTINATION as the client dials it, and paperless dials those charts' SERVICES, which listen on 80 and forward to the containers' own ports.

Warum das nicht stimmt

kube-proxy übersetzt das Ziel eines ClusterIP-Service (DNAT), bevor die Egress-Policy am Pod-Interface ausgewertet wird. Die Policy sieht also podIP:targetPort, nicht clusterIP:port. Eine Regel auf den Service-Port trifft damit nie, wenn Service-Port und Pod-Port auseinanderfallen — und genau das ist bei diesen beiden Charts der Fall:

cluster-tika-apache-tika-service      port=80 -> targetPort=tika-port      = 9998
cluster-gotenberg-gotenberg-service   port=80 -> targetPort=gotenberg-port = 3000

Das Fehlerbild, gemessen

httpx.ConnectTimeout: timed out
documents.parsers.ParseError: Could not parse content with tika server at
http://cluster-tika-apache-tika-service.cluster-tika-gotenberg.svc.cluster.local:
timed out

Die Fehlerart ist der Hinweis: Zeitüberschreitung, nicht connection refused. Ein fehlender Dienst lehnt ab, ein verworfenes Paket läuft in den Zeitablauf. Es gibt keine Meldung, die auf eine NetworkPolicy zeigt.

Umgebung: RKE2 mit rke2-canal (Flannel für das Netz, calico-node für die Durchsetzung), kube-proxy im iptables-Modus, Kubernetes 1.36.

Was es nicht betrifft

Damit die Tragweite klar ist — clusterweit nachgesehen: 58 Services haben einen vom Pod-Port abweichenden Port, aber die Egress-Regeln der Charts nennen nur diese beiden. Alles andere ist 1:1 und funktioniert:

Ziel	Abbildung
Valkey (alle Instanzen)	`6379 → 6379`
CloudNativePG	`5432 → 5432`
`minecraft-server`	`25565 → 25565`
OIDC, IMAPS (443, 993)	außerhalb des Clusters, kein DNAT

Die Egress-Regeln der anderen Charts dieses Schwungs sind also korrekt. Betroffen ist allein die Tika/Gotenberg-Regel in paperless-ngx.

Vorschlag

Die Regel sollte die Pod-Ports nennen — oder sicherheitshalber beide:

80, 9998, 3000

9998 und 3000 sind die Container-Ports, die die Charts apache-tika und gotenberg selbst deklarieren; sie stehen also fest und müssen nicht geraten werden. Die 80 mitzuführen kostet nichts und deckt eine Installation ab, deren Service wirklich auf 80 hört (etwa ein fremdes Tika hinter einem Proxy).

Dazu gehört der Kommentar berichtigt. Der Satz „an egress rule names the port on the DESTINATION as the client dials it" beschreibt, was man erwartet, und nicht, was passiert — er ist die Art Begründung, die einen Leser vom Nachprüfen abhält.

Als Prüfung im Chart-Repo: ci/run-networkpolicy-test.sh behauptet laut Kommentar, jeden Port der Policy gegen die containerPorts des ausgewählten Pod-Specs zu halten. Für Egress-Ziele in fremden Charts kann das naturgemäß nicht greifen. Eine Ergänzung, die im Install-Test eine echte Verbindung über einen ClusterIP-Service mit abweichendem Port versucht, hätte das hier gefunden.

Behelf im Cluster

In cluster-config steht die Reparatur als PR #551 (merged): egress.extraPorts: [993, 9998, 3000] in allen drei Paperless-Instanzen, mit der Messung im Kommentar. Nachgeprüft ist der ganze Weg danach — Consuming test.eml → Tika → Gotenberg → convert exited 0 → Dokument, und auf der Gegenseite ein Zugriffsprotokoll mit passendem Zeitstempel.

Die NetworkPolicy von `paperless-ngx` erlaubt ausgehend **80** für Tika und Gotenberg und begründet das ausdrücklich. Die Begründung ist falsch, und das hat am 15.10.2026 in `jlab-cluster/cluster-config` einen Ausfall verursacht: Nach dem Ausrollen von Chart `14.0.0+up3.3.1` kam Paperless nicht mehr an Tika und Gotenberg — Mail-Import, EML, HTML und Office-Dokumente fielen aus, reine PDFs und Bilder liefen weiter. ## Was im Chart steht In `values.yaml` am `networkPolicy`-Block: > **NOTE WHY THAT RULE SAYS 80 AND NOT 9998/3000:** an egress rule names the port on the DESTINATION as the client dials it, and paperless dials those charts' SERVICES, which listen on 80 and forward to the containers' own ports. ## Warum das nicht stimmt `kube-proxy` übersetzt das Ziel eines ClusterIP-Service (DNAT), **bevor** die Egress-Policy am Pod-Interface ausgewertet wird. Die Policy sieht also `podIP:targetPort`, nicht `clusterIP:port`. Eine Regel auf den **Service**-Port trifft damit nie, wenn Service-Port und Pod-Port auseinanderfallen — und genau das ist bei diesen beiden Charts der Fall: ``` cluster-tika-apache-tika-service port=80 -> targetPort=tika-port = 9998 cluster-gotenberg-gotenberg-service port=80 -> targetPort=gotenberg-port = 3000 ``` ## Das Fehlerbild, gemessen ``` httpx.ConnectTimeout: timed out documents.parsers.ParseError: Could not parse content with tika server at http://cluster-tika-apache-tika-service.cluster-tika-gotenberg.svc.cluster.local: timed out ``` **Die Fehlerart ist der Hinweis:** Zeitüberschreitung, nicht `connection refused`. Ein fehlender Dienst lehnt ab, ein verworfenes Paket läuft in den Zeitablauf. Es gibt keine Meldung, die auf eine NetworkPolicy zeigt. Umgebung: RKE2 mit `rke2-canal` (Flannel für das Netz, **calico-node** für die Durchsetzung), `kube-proxy` im iptables-Modus, Kubernetes 1.36. ## Was es nicht betrifft Damit die Tragweite klar ist — clusterweit nachgesehen: 58 Services haben einen vom Pod-Port abweichenden Port, aber die Egress-Regeln der Charts nennen nur diese beiden. Alles andere ist 1:1 und funktioniert: | Ziel | Abbildung | |---|---| | Valkey (alle Instanzen) | `6379 → 6379` | | CloudNativePG | `5432 → 5432` | | `minecraft-server` | `25565 → 25565` | | OIDC, IMAPS (443, 993) | außerhalb des Clusters, kein DNAT | Die Egress-Regeln der anderen Charts dieses Schwungs sind also korrekt. Betroffen ist allein die Tika/Gotenberg-Regel in `paperless-ngx`. ## Vorschlag Die Regel sollte die **Pod-Ports** nennen — oder sicherheitshalber beide: ``` 80, 9998, 3000 ``` `9998` und `3000` sind die Container-Ports, die die Charts `apache-tika` und `gotenberg` selbst deklarieren; sie stehen also fest und müssen nicht geraten werden. Die `80` mitzuführen kostet nichts und deckt eine Installation ab, deren Service wirklich auf 80 hört (etwa ein fremdes Tika hinter einem Proxy). Dazu gehört der Kommentar berichtigt. Der Satz „an egress rule names the port on the DESTINATION as the client dials it" beschreibt, was man erwartet, und nicht, was passiert — er ist die Art Begründung, die einen Leser vom Nachprüfen abhält. **Als Prüfung im Chart-Repo**: `ci/run-networkpolicy-test.sh` behauptet laut Kommentar, jeden Port der Policy gegen die `containerPorts` des ausgewählten Pod-Specs zu halten. Für Egress-Ziele in **fremden** Charts kann das naturgemäß nicht greifen. Eine Ergänzung, die im Install-Test eine echte Verbindung über einen ClusterIP-Service mit abweichendem Port versucht, hätte das hier gefunden. ## Behelf im Cluster In `cluster-config` steht die Reparatur als PR #551 (merged): `egress.extraPorts: [993, 9998, 3000]` in allen drei Paperless-Instanzen, mit der Messung im Kommentar. Nachgeprüft ist der ganze Weg danach — `Consuming test.eml` → Tika → Gotenberg → `convert exited 0` → Dokument, und auf der Gegenseite ein Zugriffsprotokoll mit passendem Zeitstempel.

jlab-bot commented

2026-10-15 19:33:40 +02:00

Genehmigter Plan

Die Analyse des Rumpfs ist bestätigt, einschließlich der Eingrenzung. Unabhängig nachgemessen: vier Policy-Templates nennen Port 80, aber drei davon zielen ins Internet, wo kein DNAT stattfindet und 80 der echte Zielport ist — gotenberg (remoteAssets), rss-bridge und ytdlp-web-player. Nur paperless-ngx nennt einen ClusterIP-Service-Port. Betroffen ist also genau diese eine Regel.

Was sofort entsperrt, vor jeder PR

Der Chart dokumentiert das Notventil bereits. Für das laufende Release genügt:

networkPolicy:
  egress:
    extraPorts: [9998, 3000]

Damit laufen Tika und Gotenberg wieder, unabhängig von allem Folgenden.

Umfang

1. Die Regel nennt 9998, 3000 und 80. Die 80 bleibt aus dem Grund, den der Rumpf nennt: sie kostet nichts und deckt ein fremdes Tika, dessen Service wirklich auf 80 hört.

2. Das bestehende Feature-Gate bleibt — kein eigener Schalter. Entscheidung des Maintainers. Die Regel rendert weiter nur unter paperless.files.tikaGotenberg.enabled. Ein zusätzlicher Policy-Schalter wurde ausdrücklich abgelehnt, und die Begründung ist die stärkere: ein zweiter Wert, der mit dem Feature auseinanderlaufen kann, spannt genau diesen Ausfall neu — wer Tika einschaltet und den Policy-Schalter vergisst, steht wieder hier, mit derselben Meldung, die nicht auf die Policy zeigt.

3. Der Kommentar wird ersetzt, und zwar mit dem Mechanismus und dem Hinweis, der ihn findbar macht:

kube-proxy übersetzt das Ziel eines ClusterIP-Service (DNAT), bevor die Egress-Policy am Pod-Interface ausgewertet wird. Die Policy sieht podIP:targetPort. Eine Egress-Regel nennt deshalb den Pod-Port, nie den Service-Port.
Das Fehlerbild ist eine Zeitüberschreitung, nicht connection refused. Ein fehlender Dienst lehnt ab, ein verworfenes Paket läuft in den Ablauf. Keine Meldung zeigt auf eine NetworkPolicy.
Der alte Satz gehört als widerlegt zitiert, nicht gelöscht — er klang plausibel, und das ist der Grund, warum er durchkam.

4. Neu: networkPolicy.egress.mailImport, öffnet 993 (IMAPS), Vorgabe aus. Der Chart kann es nicht wissen — paperless' Mail-Konten liegen in der Anwendungsdatenbank, nicht in den Werten. Zu dokumentieren: einfaches IMAP (143) und POP3 sind bewusst nicht mit abgedeckt und gehören in extraPorts. 993 geht nach außen, es gibt dort kein DNAT, der Port ist also der echte.

5. Eine chart-übergreifende CI-Zusicherung. Zusicherung 2 aus #5 prüft Ports gegen die selektierte Pod-Spezifikation — das greift bei Ingress, aber bei Egress liegt das Ziel in einem anderen Chart und damit außerhalb des Renders. Innerhalb eines Charts ist dieser Fehler also nicht fangbar.

Fangbar ist er chart-übergreifend, und paperless-ngx ist die einzige Stelle im Repository, an der ein Chart den Service eines anderen Charts dieses Repositories anwählt: apache-tika und gotenberg mitrendern und verlangen, dass paperless' Egress-Ports deren containerPorts enthalten. Die Fehlpfade werden mit ausgeführt, nicht nur die grünen.

6. Version Minor 14.1.0+up3.3.1 — ein additiver Wert und eine Behebung, die eine Regel weitet. Nichts bricht, kein Wert wird verpflichtend, appVersion unverändert.

7. Wiki: die paperless-ngx-Seite, CI-CD für die neue Zusicherung, und Lessons-Learned — die Lehre ist übertragbar und gehört dorthin: eine Egress-Regel nennt den Pod-Port, nicht den Service-Port, weil das Ziel-NAT vor der Policy greift; und das Symptom ist eine Zeitüberschreitung, nicht eine Ablehnung.

Zur Herkunft des Fehlers

Der Kommentar entstand mit #5. Die Hauptsitzung hatte den Mechanismus zwei Tage zuvor richtig beschrieben — „Policies greifen auch über Services, denn sie wirken an der Pod-Schnittstelle und ein Service ist nur Ziel-NAT" — und ihn für die Egress-Richtung nicht zu Ende gedacht. Die Information lag vor, die Schlussfolgerung fehlte. Das gehört in den Lessons-Learned-Eintrag, weil es erklärt, wie ein falscher Satz an mehreren Prüfungen vorbeikam.

# Genehmigter Plan Die Analyse des Rumpfs ist bestätigt, einschließlich der Eingrenzung. Unabhängig nachgemessen: **vier** Policy-Templates nennen Port 80, aber drei davon zielen **ins Internet**, wo kein DNAT stattfindet und 80 der echte Zielport ist — `gotenberg` (`remoteAssets`), `rss-bridge` und `ytdlp-web-player`. **Nur `paperless-ngx` nennt einen ClusterIP-Service-Port.** Betroffen ist also genau diese eine Regel. ## Was sofort entsperrt, vor jeder PR Der Chart dokumentiert das Notventil bereits. Für das laufende Release genügt: ```yaml networkPolicy: egress: extraPorts: [9998, 3000] ``` Damit laufen Tika und Gotenberg wieder, unabhängig von allem Folgenden. ## Umfang **1. Die Regel nennt `9998`, `3000` und `80`.** Die `80` bleibt aus dem Grund, den der Rumpf nennt: sie kostet nichts und deckt ein fremdes Tika, dessen Service wirklich auf 80 hört. **2. Das bestehende Feature-Gate bleibt — kein eigener Schalter.** Entscheidung des Maintainers. Die Regel rendert weiter nur unter `paperless.files.tikaGotenberg.enabled`. Ein zusätzlicher Policy-Schalter wurde ausdrücklich **abgelehnt**, und die Begründung ist die stärkere: ein zweiter Wert, der mit dem Feature auseinanderlaufen kann, spannt genau diesen Ausfall neu — wer Tika einschaltet und den Policy-Schalter vergisst, steht wieder hier, mit derselben Meldung, die nicht auf die Policy zeigt. **3. Der Kommentar wird ersetzt**, und zwar mit dem Mechanismus **und** dem Hinweis, der ihn findbar macht: - `kube-proxy` übersetzt das Ziel eines ClusterIP-Service (DNAT), **bevor** die Egress-Policy am Pod-Interface ausgewertet wird. Die Policy sieht `podIP:targetPort`. Eine Egress-Regel nennt deshalb den **Pod**-Port, nie den Service-Port. - **Das Fehlerbild ist eine Zeitüberschreitung, nicht `connection refused`.** Ein fehlender Dienst lehnt ab, ein verworfenes Paket läuft in den Ablauf. Keine Meldung zeigt auf eine NetworkPolicy. - Der alte Satz gehört als **widerlegt** zitiert, nicht gelöscht — er klang plausibel, und das ist der Grund, warum er durchkam. **4. Neu: `networkPolicy.egress.mailImport`**, öffnet **993** (IMAPS), Vorgabe **aus**. Der Chart kann es nicht wissen — paperless' Mail-Konten liegen in der Anwendungsdatenbank, nicht in den Werten. Zu dokumentieren: einfaches IMAP (143) und POP3 sind bewusst **nicht** mit abgedeckt und gehören in `extraPorts`. 993 geht nach außen, es gibt dort kein DNAT, der Port ist also der echte. **5. Eine chart-übergreifende CI-Zusicherung.** Zusicherung 2 aus #5 prüft Ports gegen die **selektierte** Pod-Spezifikation — das greift bei Ingress, aber bei Egress liegt das Ziel in einem anderen Chart und damit außerhalb des Renders. Innerhalb eines Charts ist dieser Fehler also **nicht** fangbar. Fangbar ist er chart-übergreifend, und `paperless-ngx` ist die **einzige** Stelle im Repository, an der ein Chart den Service eines anderen Charts dieses Repositories anwählt: `apache-tika` und `gotenberg` mitrendern und verlangen, dass paperless' Egress-Ports deren `containerPort`s enthalten. Die Fehlpfade werden mit ausgeführt, nicht nur die grünen. **6. Version Minor `14.1.0+up3.3.1`** — ein additiver Wert und eine Behebung, die eine Regel **weitet**. Nichts bricht, kein Wert wird verpflichtend, `appVersion` unverändert. **7. Wiki:** die `paperless-ngx`-Seite, `CI-CD` für die neue Zusicherung, und `Lessons-Learned` — die Lehre ist übertragbar und gehört dorthin: *eine Egress-Regel nennt den Pod-Port, nicht den Service-Port, weil das Ziel-NAT vor der Policy greift; und das Symptom ist eine Zeitüberschreitung, nicht eine Ablehnung.* ## Zur Herkunft des Fehlers Der Kommentar entstand mit #5. Die Hauptsitzung hatte den Mechanismus zwei Tage zuvor richtig beschrieben — *„Policies greifen auch über Services, denn sie wirken an der Pod-Schnittstelle und ein Service ist nur Ziel-NAT"* — und ihn für die **Egress**-Richtung nicht zu Ende gedacht. Die Information lag vor, die Schlussfolgerung fehlte. Das gehört in den `Lessons-Learned`-Eintrag, weil es erklärt, wie ein falscher Satz an mehreren Prüfungen vorbeikam.

jklein referenced this issue from a commit

2026-10-15 19:40:29 +02:00

fix(paperless-ngx): egress names the Tika/Gotenberg POD ports, not the Service port

jklein referenced this issue from a commit

2026-10-15 19:46:49 +02:00

test(ci): assert a chart's egress ports against the POD ports of the chart it dials

jlab-bot referenced a pull request that will close this issue

2026-10-15 19:47:36 +02:00

fix(paperless-ngx): the egress rule names the Tika/Gotenberg pod ports, and CI now asserts it across charts #138

jklein referenced this issue from a commit

2026-10-15 19:54:16 +02:00

docs(paperless-ngx): the policy header said TWO and listed three