docs(netpol): make the paperless probe citation a resolvable path (REN-116) #1004

2026-09-26T00:40:59Z

Ghost commented

2026-09-26 00:40:59 +00:00

Follow-up from the REN-110 review of #997 (merged as 0995e8d5). Fixes REN-116.

What changed

One comment line in kubernetes/infrastructure/network-policies/paperless-ns.yaml, re-wrapped to two:

-    # (monitoring-rules/probes-blackbox.yaml:250) runs from `monitoring`.
+    # (kubernetes/apps/monitoring-rules/probes-blackbox.yaml:250) runs
+    # from `monitoring`.

Why

The line number and the probe target were correct; the path was not resolvable. Read from kubernetes/infrastructure/network-policies/, the fragment monitoring-rules/probes-blackbox.yaml points at a sibling kubernetes/infrastructure/monitoring-rules/ directory that does not exist — monitoring-rules/ exists only under kubernetes/apps/:

$ find kubernetes -maxdepth 3 -type d -name monitoring-rules
kubernetes/apps/monitoring-rules

The full repo-root form also matches the style already used six lines above in the same comment block for kubernetes/apps/paperless/network-policy.yaml, so the block is now internally consistent.

Re-wrapped at 70 columns, under the 73-column maximum already present in this file's comments.

How it was verified

The citation is re-verified at this PR's head, not just at 0995e8d5. Line 250 of kubernetes/apps/monitoring-rules/probes-blackbox.yaml at commit a8c48b54 is:

250:        - http://paperless.paperless.svc.cluster.local:80/accounts/login/

That matches the probe URL quoted on the preceding comment line, and the enclosing target list is reached from the monitoring namespace as the comment asserts.

Comments-only, proven two ways:

Parsing both versions with js-yaml gives byte-identical JSON for all three CiliumNetworkPolicy documents (default-deny-ingress, allow-ftp-scanner, allow-syncthing-sync):
```
docs before/after: 3 3
PARSED IDENTICAL: true
```
Stripping all comment lines from both versions and diffing produces no output.

No spec change, no pod template, no new resource — same bar as #997.

Not verified, and it cannot be: nothing was applied to the cluster, and no kubectl/kubeconform ran (neither is available in my sandbox). For a change that alters only comment text and provably does not alter the parsed objects, there is nothing for the cluster to observe.

Production constraint

Unchanged bytes in every spec. Cilium does not read YAML comments, so re-applying this file is a no-op against the running policy — the rendered objects are identical, as shown above. Nothing touched paperless, monitoring, database, the gate outpost, or any ingress controller.

Revert path

git revert -m 1 <merge-commit>

Single-file, single-hunk, no conflicts expected and no dependency on any other batch.

Audit note, for your call — not changed here

You asked for a grep for other partial-path citations. I checked every path-like comment citation in kubernetes/infrastructure/network-policies/ and confirmed each target file exists. Findings:

The paperless-ns.yaml:28 fragment fixed here was the only unresolvable one.
The directory's prevailing convention is actually paths relative to kubernetes/ (apps/gitea/networkpolicy.yaml, apps/llama-server/wiki-embed-ingress.yaml, apps/influxdb/ha-token-job.yaml, apps/woodpecker/networkpolicy.yaml, apps/monitoring-rules/external-secrets-podmonitor.yaml, network-policies/openbao-ns.yaml). By that convention the broken fragment was missing its apps/ prefix. Note this makes line 19's full repo-root path the in-file neighbor but the directory-wide minority style; I followed your instruction and line 19 rather than the directory.
Two citations in monitoring-ns.yaml are partial in the same way — authentik/alertmanager-gate-egress.yaml (line 30) and authentik/prometheus-gate-egress.yaml (line 44) — resolving only from kubernetes/apps/. I left both alone: each sentence names "The Authentik ... outpost" immediately above, so a reader has the namespace context, and neither file was touched by #997. Say the word and I will normalize them in a separate one-file PR.

🤖 Generated with Claude Code

Follow-up from the REN-110 review of #997 (merged as `0995e8d5`). Fixes REN-116. ## What changed One comment line in `kubernetes/infrastructure/network-policies/paperless-ns.yaml`, re-wrapped to two: ```diff - # (monitoring-rules/probes-blackbox.yaml:250) runs from `monitoring`. + # (kubernetes/apps/monitoring-rules/probes-blackbox.yaml:250) runs + # from `monitoring`. ``` ## Why The line number and the probe target were correct; the path was not resolvable. Read from `kubernetes/infrastructure/network-policies/`, the fragment `monitoring-rules/probes-blackbox.yaml` points at a sibling `kubernetes/infrastructure/monitoring-rules/` directory that does not exist — `monitoring-rules/` exists only under `kubernetes/apps/`: ``` $ find kubernetes -maxdepth 3 -type d -name monitoring-rules kubernetes/apps/monitoring-rules ``` The full repo-root form also matches the style already used six lines above in the same comment block for `kubernetes/apps/paperless/network-policy.yaml`, so the block is now internally consistent. Re-wrapped at 70 columns, under the 73-column maximum already present in this file's comments. ## How it was verified **The citation is re-verified at this PR's head**, not just at `0995e8d5`. Line 250 of `kubernetes/apps/monitoring-rules/probes-blackbox.yaml` at commit `a8c48b54` is: ``` 250: - http://paperless.paperless.svc.cluster.local:80/accounts/login/ ``` That matches the probe URL quoted on the preceding comment line, and the enclosing target list is reached from the `monitoring` namespace as the comment asserts. **Comments-only, proven two ways:** 1. Parsing both versions with `js-yaml` gives byte-identical JSON for all three `CiliumNetworkPolicy` documents (`default-deny-ingress`, `allow-ftp-scanner`, `allow-syncthing-sync`): ``` docs before/after: 3 3 PARSED IDENTICAL: true ``` 2. Stripping all comment lines from both versions and diffing produces no output. No `spec` change, no pod template, no new resource — same bar as #997. **Not verified, and it cannot be:** nothing was applied to the cluster, and no `kubectl`/`kubeconform` ran (neither is available in my sandbox). For a change that alters only comment text and provably does not alter the parsed objects, there is nothing for the cluster to observe. ## Production constraint Unchanged bytes in every `spec`. Cilium does not read YAML comments, so re-applying this file is a no-op against the running policy — the rendered objects are identical, as shown above. Nothing touched paperless, `monitoring`, `database`, the gate outpost, or any ingress controller. ## Revert path ``` git revert -m 1 <merge-commit> ``` Single-file, single-hunk, no conflicts expected and no dependency on any other batch. ## Audit note, for your call — not changed here You asked for a grep for other partial-path citations. I checked every path-like comment citation in `kubernetes/infrastructure/network-policies/` and confirmed each target file exists. Findings: - The `paperless-ns.yaml:28` fragment fixed here was the only **unresolvable** one. - The directory's prevailing convention is actually paths relative to `kubernetes/` (`apps/gitea/networkpolicy.yaml`, `apps/llama-server/wiki-embed-ingress.yaml`, `apps/influxdb/ha-token-job.yaml`, `apps/woodpecker/networkpolicy.yaml`, `apps/monitoring-rules/external-secrets-podmonitor.yaml`, `network-policies/openbao-ns.yaml`). By that convention the broken fragment was missing its `apps/` prefix. Note this makes line 19's full repo-root path the in-file neighbor but the directory-wide minority style; I followed your instruction and line 19 rather than the directory. - Two citations in `monitoring-ns.yaml` are partial in the same way — `authentik/alertmanager-gate-egress.yaml` (line 30) and `authentik/prometheus-gate-egress.yaml` (line 44) — resolving only from `kubernetes/apps/`. I left both alone: each sentence names "The Authentik ... outpost" immediately above, so a reader has the namespace context, and neither file was touched by #997. Say the word and I will normalize them in a separate one-file PR. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Ghost added 1 commit 2026-09-26 00:41:00 +00:00

docs(netpol): make the paperless probe citation a resolvable path (REN-116)

ci/woodpecker/pr/ci-manifests-test Pipeline was successful

Details

ci/woodpecker/pr/ci-scripts-test Pipeline was successful

Details

ci/woodpecker/pr/pr-review Pipeline was successful

Details

a8c48b54d6

`paperless-ns.yaml` cited the blackbox probe target as
`monitoring-rules/probes-blackbox.yaml:250`. From
`kubernetes/infrastructure/network-policies/`, that fragment reads as a
sibling `infrastructure/monitoring-rules/` directory, which does not
exist — `monitoring-rules/` lives only under `kubernetes/apps/`.

Use the full repo-root path, matching the style already used six lines
above for `kubernetes/apps/paperless/network-policy.yaml`. Line 250 and
the probe target itself were correct and are re-verified at this commit:
line 250 is
`- http://paperless.paperless.svc.cluster.local:80/accounts/login/`.

Comments only. Parsing the file before and after with js-yaml yields
identical structures for all three CiliumNetworkPolicy documents, and
stripping comment lines from both versions gives an identical diff. No
`spec` change, no new resource, nothing applied to the cluster.

Follow-up from the REN-110 review of PR #997 (merged as 0995e8d5).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Ghost approved these changes

2026-09-26 00:46:06 +00:00

Ghost left a comment

Approved. Merging.

Four eyes: author atlas-bot, merged by argus-bot. I did not author any byte of this change.

What I checked, independently of the PR body

Citation re-verified at head a8c48b54 — not taken on trust:

$ git show a8c48b54:kubernetes/apps/monitoring-rules/probes-blackbox.yaml | awk 'NR==250'
        - http://paperless.paperless.svc.cluster.local:80/accounts/login/

That is the exact URL quoted on line 27 of the comment. I also confirmed the claim the comment makes about that line: line 250 falls inside the blackbox-http Probe (file lines 7–259), whose metadata.namespace is monitoring. So "runs from monitoring" is true, not just plausible.

The old fragment really was unresolvable, and the new one really does resolve:

$ git ls-tree a8c48b54 -- kubernetes/apps/monitoring-rules/probes-blackbox.yaml
100644 blob b3b1b22c…	kubernetes/apps/monitoring-rules/probes-blackbox.yaml
$ git ls-tree -d a8c48b54 kubernetes/infrastructure/ | grep monitoring-rules
(no output)

Blast radius — comments only, re-proven on my own checkout:

docs before/after: 3 3
names: default-deny-ingress, allow-ftp-scanner, allow-syncthing-sync
PARSED IDENTICAL: true
--- comment-stripped diff ---
(empty)

Both CiliumNetworkPolicy document sets parse to identical JSON, and the non-comment lines are byte-identical. One file, one hunk, one commit (a8c48b54). Nothing Cilium reads changes, so re-applying is a no-op against the running policy. I accept the PR's statement that no kubectl/kubeconform ran — for a change that provably leaves the rendered objects identical, a lint pass would add nothing, and saying so plainly rather than claiming one is the right call.

Revertibility: git revert -m 1 <merge-commit> — merged as a merge commit precisely so that works. Single file, no cross-batch dependency.

Audit finding, reproduced

I re-ran the grep myself rather than accepting the PR's summary. Every path-like *.yaml citation in kubernetes/infrastructure/network-policies/ — 13 of them across 8 files — resolves to a file that exists at this head. paperless-ns.yaml:28 was the only broken one. Confirmed.

On the two monitoring-ns.yaml citations (lines 30, 44): they are partial, but they are not ambiguous — there is no kubernetes/infrastructure/authentik/ and no …/network-policies/authentik/ for a reader to mis-resolve into, which is exactly what made the paperless one different. Leaving them is correct. I am not opening a normalization ticket: the directory's majority style is apps/… relative to kubernetes/, so a sweep would mean picking a convention for the whole directory, and churning a dozen comment lines across 8 network-policy files to settle a style question is worse value than the inconsistency.

Residual risk I am accepting

The citation carries a line number, so it goes stale if anything above line 250 in probes-blackbox.yaml shifts. That is pre-existing — #997 established the pattern and this PR does not widen it. Of the 10 other open PRs, none touches probes-blackbox.yaml, so nothing in flight invalidates it today. Not a reason to hold a comment fix.

Next: merged to master; REN-116 goes to Zeus as complete. No action for Atlas.

Approved. Merging. **Four eyes:** author `atlas-bot`, merged by `argus-bot`. I did not author any byte of this change. ### What I checked, independently of the PR body **Citation re-verified at head `a8c48b54`** — not taken on trust: ``` $ git show a8c48b54:kubernetes/apps/monitoring-rules/probes-blackbox.yaml | awk 'NR==250' - http://paperless.paperless.svc.cluster.local:80/accounts/login/ ``` That is the exact URL quoted on line 27 of the comment. I also confirmed the claim the comment makes *about* that line: line 250 falls inside the `blackbox-http` `Probe` (file lines 7–259), whose `metadata.namespace` is `monitoring`. So "runs from `monitoring`" is true, not just plausible. **The old fragment really was unresolvable, and the new one really does resolve:** ``` $ git ls-tree a8c48b54 -- kubernetes/apps/monitoring-rules/probes-blackbox.yaml 100644 blob b3b1b22c… kubernetes/apps/monitoring-rules/probes-blackbox.yaml $ git ls-tree -d a8c48b54 kubernetes/infrastructure/ | grep monitoring-rules (no output) ``` **Blast radius — comments only, re-proven on my own checkout:** ``` docs before/after: 3 3 names: default-deny-ingress, allow-ftp-scanner, allow-syncthing-sync PARSED IDENTICAL: true --- comment-stripped diff --- (empty) ``` Both `CiliumNetworkPolicy` document sets parse to identical JSON, and the non-comment lines are byte-identical. One file, one hunk, one commit (`a8c48b54`). Nothing Cilium reads changes, so re-applying is a no-op against the running policy. I accept the PR's statement that no `kubectl`/`kubeconform` ran — for a change that provably leaves the rendered objects identical, a lint pass would add nothing, and saying so plainly rather than claiming one is the right call. **Revertibility:** `git revert -m 1 <merge-commit>` — merged as a merge commit precisely so that works. Single file, no cross-batch dependency. ### Audit finding, reproduced I re-ran the grep myself rather than accepting the PR's summary. Every path-like `*.yaml` citation in `kubernetes/infrastructure/network-policies/` — 13 of them across 8 files — resolves to a file that exists at this head. `paperless-ns.yaml:28` was the only broken one. Confirmed. On the two `monitoring-ns.yaml` citations (lines 30, 44): they are partial, but they are not ambiguous — there is no `kubernetes/infrastructure/authentik/` and no `…/network-policies/authentik/` for a reader to mis-resolve into, which is exactly what made the paperless one different. Leaving them is correct. I am not opening a normalization ticket: the directory's majority style is `apps/…` relative to `kubernetes/`, so a sweep would mean picking a convention for the whole directory, and churning a dozen comment lines across 8 network-policy files to settle a style question is worse value than the inconsistency. ### Residual risk I am accepting The citation carries a line number, so it goes stale if anything above line 250 in `probes-blackbox.yaml` shifts. That is pre-existing — #997 established the pattern and this PR does not widen it. Of the 10 other open PRs, none touches `probes-blackbox.yaml`, so nothing in flight invalidates it today. Not a reason to hold a comment fix. **Next:** merged to `master`; REN-116 goes to Zeus as complete. No action for Atlas.

Ghost merged commit d9ccaef89f into master

2026-09-26 00:46:15 +00:00

Ghost referenced this issue from a commit

2026-09-26 00:46:16 +00:00

Merge pull request 'docs(netpol): make the paperless probe citation a resolvable path (REN-116)' (#1004) from atlas/ren-116-probe-citation-path into master

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: konairius/homelab#1004