paperless-ngx/templates/paperless-server.networkpolicy.yaml

@@ -86,7 +86,18 @@ that the egress rule below contains their containerPorts.
        for "ingress"; one round of this work already mistook the second for an
        inbound escape hatch on the strength of the substring. */}}
 {{- $npIngress := $np.ingress | default dict }}
-{{- $ambientMesh := $npIngress.ambientMesh }}
+{{- /* NULL-SAFE ON PURPOSE (#99): ambientMesh is an OBJECT, so every read goes
+       through a fallback reproducing THIS chart's declared defaults. An
+       operator who deletes the object, or writes only "enabled: true", must
+       land on the defaults and not in a nil dereference - #136 shipped exactly
+       that defect one value away, where the NOTES.txt branch dereferenced
+       .networkPolicy.egress directly. Clearing the probe-source list restores
+       the constant rather than removing the ipBlock, deliberately: the two
+       halves are not separable, and enabled: false is how you open nothing. */}}
+{{- $ambient := $npIngress.ambientMesh | default dict }}
+{{- $ambientEnabled := $ambient.enabled }}
+{{- $ambientPort := $ambient.port | default 15008 }}
+{{- $ambientProbeSources := $ambient.redirectedProbeSources | default (list "169.254.7.127/32") }}
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
 metadata:
@@ -121,7 +132,7 @@ spec:
     - ports:
         - protocol: TCP
           port: 8000
-        {{- if $ambientMesh }}
+        {{- if $ambientEnabled }}
         {{- /* FIRST HALF OF networkPolicy.ingress.ambientMesh (Gitea #143). 15008/TCP
                is ztunnel's HBONE tunnel, the port every inbound connection arrives on
                once the namespace carries istio.io/dataplane-mode - ambient "does not
@@ -135,11 +146,22 @@ spec:
                second render, that 15008 stays the ONLY such port and that it is absent
                while the value is false.
 
+               AN ISTIO CONSTANT, NOT A STANDARD: 15008 is not registered with
+               IANA for this, no protocol prescribes it, and Kubernetes knows
+               nothing about it - Istio picked it for HBONE and Istio can change
+               it. Hence a VALUE with a documented default rather than a literal
+               here, so an operator can correct it without a chart release. Read
+               for ztunnel 1.30.6. The exception ci/run-networkpolicy-test.sh
+               grants is pinned to the number THAT TEST names, plus a check that
+               this chart declares the same default - never to whatever the value
+               says, because that would let a mistyped port ride in through a
+               configurable field (design A of #143).
+
                NOT MEASURED: that 15008 alone suffices comes from Istio's
                documentation. Measured on this cluster is only which listeners ztunnel
                opens. Provable at the first namespace to join the mesh; none has. */}}
         - protocol: TCP
-          port: 15008
+          port: {{ int $ambientPort }}
         {{- end }}
       {{- if $probeSources }}
       {{- /*
@@ -183,7 +205,7 @@ spec:
         - ipBlock:
             cidr: {{ . | quote }}
         {{- end }}
-        {{- if $ambientMesh }}
+        {{- if $ambientEnabled }}
         {{- /* SECOND HALF OF networkPolicy.ingress.ambientMesh, and the reason it is
                one value and not two. Inside the mesh the kubelet's probes are
                redirected and no longer arrive from the worker node's address: they
@@ -201,11 +223,29 @@ spec:
                counterpart is deliberately absent - this cluster is SingleStack IPv4,
                and an ipBlock of the wrong family is accepted and matches nothing.
 
+               WHERE 169.254.7.127 COMES FROM - vendor magic, not protocol:
+               it is LINK-LOCAL (169.254.0.0/16, RFC 3927), a range reserved for
+               node-local use and never routed; Istio's IPv6 counterpart
+               fd16:9254:7127:1337:ffff:ffff:ffff:ffff carries the SAME DIGITS
+               plus 1337; and KUBERNETES DOES NOT KNOW THE ADDRESS - neither the
+               NetworkPolicy API nor the kubelet - only Istio's data plane
+               rewrites the probe source onto it. Read for ztunnel 1.30.6, and if
+               Istio changes it THE FAILURE IS SILENT: probes dropped, and only
+               where probeSources is non-empty, which is nowhere today.
+
+               A LIST, not a string, and the one case where that does not
+               contradict "a constant, not a configuration": a DUAL-STACK cluster
+               needs BOTH entries at once. This cluster is SingleStack IPv4, so
+               the IPv6 counterpart is left out - an ipBlock of the wrong family
+               is accepted and matches nothing. Add it ALONGSIDE, never instead.
+
                UNPROVEN IN OPERATION: probeSources is empty in every chart here, so no
                release reaches this branch. CI proves its render, through the overlays
                in ci/networkpolicy. */}}
+        {{- range $ambientProbeSources }}
         - ipBlock:
-            cidr: 169.254.7.127/32
+            cidr: {{ . | quote }}
+        {{- end }}
         {{- end }}
       {{- else }}
       {{- /*

paperless-ngx/values.schema.json

@@ -93,8 +93,28 @@
           "additionalProperties": false,
           "properties": {
             "ambientMesh": {
-              "description": "Opens the pod for Istio's ambient mesh; off by default and additive, so the render is byte-identical while it is false. Renders 15008/TCP inbound - ztunnel's HBONE tunnel, which ambient explicitly does not let bypass NetworkPolicy enforcement - AND, where probeSources is non-empty, 169.254.7.127/32 as an additional probe source, because inside the mesh the kubelet's probes are redirected away from the worker node's address. The two halves are inseparable on purpose: whoever opens 15008 by hand has not added the probe address, and the first narrowed probeSources then drops every probe, so the pod never becomes Ready and the symptom reads as a broken application rather than as a policy. Unproven in operation: that 15008 alone suffices comes from Istio's documentation, and no namespace of this cluster carries istio.io/dataplane-mode yet.",
+              "description": "Opens the pod for Istio's ambient mesh; off by default and additive, so the render is byte-identical while enabled is false. Renders the HBONE port inbound AND, where networkPolicy.probeSources is non-empty, the redirected probe source in the same \"from\" list. The two halves live in one object under one switch on purpose: whoever opens the port by hand has not added the probe address, and the first narrowed probeSources then drops every probe, so the pod never becomes Ready and the symptom reads as a broken application rather than as a policy. Both numbers are ISTIO CONSTANTS rather than standards, which is why they are values with documented defaults and not template literals - a vendor constant can change, and an operator should be able to correct it without waiting for a chart release. Deleting the whole object is safe: every read falls back to the defaults the chart declares. Unproven in operation: that the HBONE port alone suffices comes from Istio's documentation, and no namespace of this cluster carries istio.io/dataplane-mode yet.",
+              "type": ["object", "null"],
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "description": "The switch. Everything else in this object is inert while it is false.",
                   "type": ["boolean", "null"]
+                },
+                "port": {
+                  "description": "Istio's HBONE port, default 15008. A constant Istio chose, not a standard: not registered with IANA for this, prescribed by no protocol, and unknown to Kubernetes. Read for ztunnel 1.30.6. It is the one ingress port of these charts that is deliberately no containerPort - ztunnel terminates it, not the application - and the exception ci/run-networkpolicy-test.sh grants it is pinned to the number THAT TEST knows, plus an assertion that this chart declares the same default. Not to whatever this value says: a value-driven exception would let a mistyped port ride in through a configurable field.",
+                  "type": ["integer", "null"],
+                  "minimum": 1,
+                  "maximum": 65535
+                },
+                "redirectedProbeSources": {
+                  "description": "Sources the kubelet's probes arrive from once Istio has redirected them, default [169.254.7.127/32]. NOT the same value as networkPolicy.probeSources one level up: that one holds YOUR worker node CIDRs, is empty by default and means OPEN when empty, and the chart cannot know those addresses; this one holds ISTIO's rewrite address and ships filled, because unlike the node IPs it is a constant the chart can know. Recognisable as vendor magic rather than protocol: it is link-local (169.254.0.0/16, RFC 3927, never routed), Istio's IPv6 counterpart fd16:9254:7127:1337:ffff:ffff:ffff:ffff carries the same digits plus 1337, and Kubernetes itself knows the address in neither the NetworkPolicy API nor the kubelet. A list and not a string because a dual-stack cluster needs BOTH entries at once; this cluster is SingleStack IPv4, so the IPv6 counterpart is left out of the default - an ipBlock of the wrong family is accepted and matches nothing. If Istio changes the address the failure is SILENT: probes dropped, and only where probeSources is non-empty.",
+                  "type": ["array", "null"],
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
             }
           }
         },

paperless-ngx/values.yaml

@@ -685,7 +685,85 @@ networkPolicy:
     # IPs in istio-system (measured: no hostNetwork on the DaemonSet, Istio
     # 1.30.6), so if one proves necessary it is expressible as a
     # namespaceSelector plus podSelector and needs no unknowable node CIDR.
-    ambientMesh: false
+    # BOTH NUMBERS BELOW ARE ISTIO CONSTANTS, NOT STANDARDS, and they are values
+    # rather than template literals for exactly that reason: a vendor constant
+    # can change, and an operator should be able to correct it without waiting
+    # for a chart release. Their provenance is written on each one.
+    #
+    # DELETING THIS OBJECT IS SAFE. Every read falls back to the defaults
+    # declared here (#99), so "ambientMesh: null", or an object carrying only
+    # "enabled: true", renders the documented defaults instead of failing.
+    ambientMesh:
+      # The switch. Everything else here is inert while it is false, and the
+      # chart renders exactly as it did before the object existed.
+      enabled: false
+
+      # ISTIO'S HBONE PORT. A constant Istio chose, not a standard: not
+      # registered with IANA for this, prescribed by no protocol, and unknown to
+      # Kubernetes. Read for ztunnel 1.30.6 (measured on this cluster: ztunnel
+      # opens [::]:15008 as its inbound listener).
+      #
+      # If Istio changes it, a pod in the mesh cannot be reached. Change it here
+      # in all 30 charts AND in the pinned expectation inside
+      # ci/run-networkpolicy-test.sh - the test is deliberately what forces
+      # someone to look, because the exception it grants this port is pinned to
+      # the number IT knows and not to whatever this value says. A value-driven
+      # exception would let a mistyped port through, which is the hole design A
+      # of #143 was rejected for.
+      #
+      # NOT MEASURED: that this port ALONE suffices comes from Istio's
+      # documentation. Measured here is only which listeners ztunnel opens, and
+      # no namespace carries istio.io/dataplane-mode yet.
+      port: 15008
+
+      # SOURCES THE KUBELET'S PROBES ARRIVE FROM ONCE ISTIO HAS REDIRECTED THEM.
+      #
+      # NOT THE SAME VALUE AS networkPolicy.probeSources one level up, and the
+      # two are easy to confuse, so:
+      #
+      #   networkPolicy.probeSources
+      #       YOUR worker node CIDRs. Empty by default, and empty means the
+      #       probe rule is OPEN. The chart cannot know these addresses.
+      #   networkPolicy.ingress.ambientMesh.redirectedProbeSources
+      #       ISTIO's rewrite address. Shipped filled, because unlike the node
+      #       IPs it is a constant the chart CAN know. Only rendered where the
+      #       rule above is restricted, i.e. where probeSources is non-empty.
+      #
+      # WHERE 169.254.7.127 COMES FROM - vendor magic, not protocol:
+      #
+      #   - LINK-LOCAL, 169.254.0.0/16 (RFC 3927): a range reserved for
+      #     node-local use that is never routed - exactly the range one picks a
+      #     vendor's magic address out of.
+      #   - Istio's IPv6 counterpart gives it away:
+      #     fd16:9254:7127:1337:ffff:ffff:ffff:ffff carries the SAME DIGITS
+      #     (9254:7127 is 169.254.7.127) plus 1337. Numbers built that way are
+      #     vendor constants, not protocols.
+      #   - KUBERNETES DOES NOT KNOW THIS ADDRESS. Neither the NetworkPolicy API
+      #     nor the kubelet has any notion of it; only Istio's own data plane
+      #     rewrites the probe source onto it.
+      #
+      # Read for ztunnel 1.30.6. IF ISTIO CHANGES IT, THE FAILURE IS SILENT:
+      # probes would be dropped, and only where probeSources is non-empty - which
+      # is nowhere in this repository today - so nothing here and nothing in
+      # Kubernetes would report it. What to re-check then: the address Istio's
+      # release notes name for probe redirection, this list in all 30 charts, and
+      # the pinned expectation in ci/run-networkpolicy-test.sh.
+      #
+      # A LIST, not a string, and the one case where that does not contradict "a
+      # constant, not a configuration": on a DUAL-STACK cluster BOTH entries are
+      # needed at the same time, not one of two. This cluster is SingleStack
+      # IPv4, so the IPv6 counterpart is left out - an ipBlock of the wrong
+      # family is accepted by the API server and matches nothing. Add it
+      # ALONGSIDE, never instead, if the cluster gains IPv6.
+      #
+      # Clearing this list restores the default rather than removing the ipBlock,
+      # deliberately: the two halves of this switch are not separable. To not
+      # open the port at all, set enabled: false.
+      #
+      # UNPROVEN IN OPERATION: probeSources is empty in every chart here, so no
+      # release reaches this branch. CI proves the render, not the effect.
+      redirectedProbeSources:
+        - 169.254.7.127/32
 
   egress:
     # Outbound IMAPS (993) for paperless' mail import. OFF, and it has to be a