docs(authentik): trim the blueprint comments, keep every ordering rule #688

2026-08-28T05:17:49Z

claude-bot commented

2026-08-28 05:17:49 +00:00

559 → 509 Kommentarzeilen. Ein viel kleinerer Schnitt als bei den anderen Dateien — und das ist das ehrliche Ergebnis: der Großteil hier ist Begründung pro Blueprint-Eintrag, und der Kommentar ist der einzige Ort, an dem die Bedingung überhaupt steht.

Alles Tragende bleibt, und bleibt betont:

Jede ORDER-MATTERS-Notiz überlebt — Application vor Provider, Application vor Provider vor Outpost. Application.provider ist on_delete=PROTECT, und die falsche Reihenfolge lässt das Blueprint ohne erkennbaren Grund scheitern.
Beide „Git besitzt die Mitgliedschaft, Leute HIER eintragen, nicht in der UI"-Hinweise. Ein Blueprint-Apply macht UI-Änderungen an diesen Gruppen stillschweigend rückgängig.
Warum jedes Gate überhaupt existiert: code-server läuft mit --auth=none als root über HAs secrets.yaml im Klartext, und shelly-manager hat gar keine Authentifizierung.

Gekürzt wurden die Herleitungen: warum das doppelte OAuth2-Setup auf einen Provider zusammengelegt wurde, die vollständige W3C-Spec-Erklärung zu credentials: omit, der Absatz, der rekonstruiert, wie das music-assistant-Gate scheiterte. Die Anweisung daraus bleibt, geschärft zu „kein Gate vor eine PWA setzen".

Zwei veraltete Stellen sind mit rausgefallen: der paperless-Kommentar nannte ingress-nginx als das, was auf den Outpost routet — es gibt keinen ingress-nginx mehr, Traefik ist die einzige IngressClass. Und eine liegengebliebene Anweisung, etwas „via the Authentik UI once everythings confirmed working" zu löschen, aus einer längst abgeschlossenen Sitzung.

Zusätzlich geprüft, weil es hier nötig war: diese Kommentare stehen innerhalb des eingebetteten Blueprint-Strings. Eine kaputte Einrückung würde also sauber rendern und erst scheitern, wenn Authentik das Blueprint parst. Ich habe deshalb die gerenderte ConfigMap ausgepackt und k8s-outposts.yaml separat geparst — gültig, und weiterhin 74 Einträge.

**559 → 509** Kommentarzeilen. Ein viel kleinerer Schnitt als bei den anderen Dateien — und das ist das ehrliche Ergebnis: der Großteil hier ist Begründung pro Blueprint-Eintrag, und der Kommentar ist der einzige Ort, an dem die Bedingung überhaupt steht. **Alles Tragende bleibt, und bleibt betont:** - **Jede** ORDER-MATTERS-Notiz überlebt — Application vor Provider, Application vor Provider vor Outpost. `Application.provider` ist `on_delete=PROTECT`, und die falsche Reihenfolge lässt das Blueprint ohne erkennbaren Grund scheitern. - Beide „Git besitzt die Mitgliedschaft, Leute HIER eintragen, nicht in der UI"-Hinweise. Ein Blueprint-Apply macht UI-Änderungen an diesen Gruppen stillschweigend rückgängig. - Warum jedes Gate überhaupt existiert: code-server läuft mit `--auth=none` als root über HAs `secrets.yaml` im Klartext, und shelly-manager hat gar keine Authentifizierung. **Gekürzt wurden die Herleitungen:** warum das doppelte OAuth2-Setup auf einen Provider zusammengelegt wurde, die vollständige W3C-Spec-Erklärung zu `credentials: omit`, der Absatz, der rekonstruiert, wie das music-assistant-Gate scheiterte. Die **Anweisung** daraus bleibt, geschärft zu „kein Gate vor eine PWA setzen". **Zwei veraltete Stellen** sind mit rausgefallen: der paperless-Kommentar nannte **ingress-nginx** als das, was auf den Outpost routet — es gibt keinen ingress-nginx mehr, Traefik ist die einzige IngressClass. Und eine liegengebliebene Anweisung, etwas „via the Authentik UI once everythings confirmed working" zu löschen, aus einer längst abgeschlossenen Sitzung. --- **Zusätzlich geprüft, weil es hier nötig war:** diese Kommentare stehen **innerhalb** des eingebetteten Blueprint-Strings. Eine kaputte Einrückung würde also sauber rendern und erst scheitern, wenn Authentik das Blueprint parst. Ich habe deshalb die gerenderte ConfigMap ausgepackt und `k8s-outposts.yaml` separat geparst — gültig, und weiterhin **74 Einträge**.

claude-bot added 1 commit 2026-08-28 05:17:49 +00:00

docs(authentik): trim the blueprint comments, keep every ordering rule

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

Details

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

Details

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

Details

aac2599e5f

559 -> 509 comment lines. A far smaller cut than the other files, and that is
the honest result: most of this file is per-entry rationale for a declarative
blueprint, where the comment is the only place the constraint is written down.

Everything load-bearing stays, and stays emphasised. Every ORDER MATTERS note
survives — Application before Provider, Application before Provider before
Outpost — because Application.provider is on_delete=PROTECT and getting the
order wrong leaves the blueprint failing to apply with no obvious cause. So do
both "git owns membership, add and remove people HERE not in the UI" notes,
since blueprint apply silently reverts UI edits to those groups. So does the
reason each gate exists at all: code-server runs --auth=none as root over
plaintext HA secrets, and shelly-manager has no authentication whatsoever.

Cut: the derivations. Why the dual-OAuth2 setup was collapsed into one
provider, the full W3C-spec account of credentials:'omit', a paragraph
reconstructing how the music-assistant gate failed. The instruction that came
out of that last one is kept and sharpened into "do not reintroduce a gate in
front of a PWA".

Two stale things went with it. The paperless proxy comment said the ingress
controller "only routes paperless.renner.uno to the outpost service" and named
ingress-nginx as that controller — there is no ingress-nginx left, Traefik is
the only IngressClass. And a leftover instruction to "delete via the Authentik
UI once everything's confirmed working" from a session long finished.

Verified beyond the usual: these comments live INSIDE the embedded blueprint
string, so a broken indent would render fine and only fail when Authentik
parses it. Extracted the rendered ConfigMap's k8s-outposts.yaml and parsed it
separately — valid, and still 74 entries.

review-bot reviewed

2026-08-28 05:20:28 +00:00

review-bot left a comment

🤖 Automated review — model CLI default (complexity: complex), commit aac2599e5f9b5bdca462d38316030fd8dfdd21ca.

Advisory review by the review-bot pipeline. It never approves; a human merges. Push new commits to get a fresh review.

Summary

This PR trims prose in the comments embedded in kubernetes/apps/authentik/blueprints-configmap.yaml (559 → 509 comment lines), condensing derivations/rationale while keeping every ORDER-MATTERS note, the "Git owns membership" warnings, and the security rationale for each gate. I diffed the patch against a comment-only filter (^[+-]\s*[^\s#+-]) and confirmed every added/removed line is a # comment — no model:, identifiers:, attrs:, or other blueprint keys changed. This is a documentation-only change with no functional risk.

No blocking issues.

🟡 Suggestions

kubernetes/apps/authentik/blueprints-configmap.yaml:189-193 and :237-241 — the pre-trim comments pointed at specific files backing the "CNP admits :8080 from the gate alone" claim (home-assistant-ns.yaml, vscode-gate-egress.yaml, shelly-manager-gate-egress.yaml). I confirmed these files still exist (kubernetes/infrastructure/network-policies/home-assistant-ns.yaml, kubernetes/apps/authentik/vscode-gate-egress.yaml, kubernetes/apps/authentik/shelly-manager-gate-egress.yaml), so the removed detail was accurate, not stale. Dropping the explicit pointers is a reasonable trade for brevity, but if a future reader needs to verify the CNP claim, they now have to search for it rather than jump straight to it. Not blocking — just flagging the trade-off the PR body doesn't call out (it only mentions two inaccurate deletions: the ingress-nginx reference and the stale "delete via UI" note).
The PR body's claim that Traefik is the only remaining IngressClass checks out — I grepped all ingressClassName occurrences in the repo and every one is traefik, confirming the removed ingress-nginx comment (old blueprints-configmap.yaml:65-66) really was stale and correctly cut.

Tests

No tests apply — this is a comment-only change in an embedded YAML blueprint string. The PR author states they unpacked the rendered ConfigMap and parsed k8s-outposts.yaml separately to confirm it's still valid YAML with 74 entries; I independently verified via a comment-only diff filter that no non-comment line changed, which is the strongest possible guarantee here (a parse check confirms validity, but the line-level diff filter confirms nothing structural moved at all).

Recommendation

Looks reasonable — no blocking issues; comments above are optional.

🤖 **Automated review** — model `CLI default` (complexity: complex), commit `aac2599e5f9b5bdca462d38316030fd8dfdd21ca`. > Advisory review by the `review-bot` pipeline. It never approves; a human merges. Push new commits to get a fresh review. --- ## Summary This PR trims prose in the comments embedded in `kubernetes/apps/authentik/blueprints-configmap.yaml` (559 → 509 comment lines), condensing derivations/rationale while keeping every ORDER-MATTERS note, the "Git owns membership" warnings, and the security rationale for each gate. I diffed the patch against a comment-only filter (`^[+-]\s*[^\s#+-]`) and confirmed **every** added/removed line is a `#` comment — no `model:`, `identifiers:`, `attrs:`, or other blueprint keys changed. This is a documentation-only change with no functional risk. No blocking issues. ## 🟡 Suggestions - **`kubernetes/apps/authentik/blueprints-configmap.yaml:189-193` and `:237-241`** — the pre-trim comments pointed at specific files backing the "CNP admits :8080 from the gate alone" claim (`home-assistant-ns.yaml`, `vscode-gate-egress.yaml`, `shelly-manager-gate-egress.yaml`). I confirmed these files still exist (`kubernetes/infrastructure/network-policies/home-assistant-ns.yaml`, `kubernetes/apps/authentik/vscode-gate-egress.yaml`, `kubernetes/apps/authentik/shelly-manager-gate-egress.yaml`), so the removed detail was accurate, not stale. Dropping the explicit pointers is a reasonable trade for brevity, but if a future reader needs to verify the CNP claim, they now have to search for it rather than jump straight to it. Not blocking — just flagging the trade-off the PR body doesn't call out (it only mentions two *inaccurate* deletions: the ingress-nginx reference and the stale "delete via UI" note). - The PR body's claim that Traefik is the only remaining IngressClass checks out — I grepped all `ingressClassName` occurrences in the repo and every one is `traefik`, confirming the removed `ingress-nginx` comment (old `blueprints-configmap.yaml:65-66`) really was stale and correctly cut. ## Tests No tests apply — this is a comment-only change in an embedded YAML blueprint string. The PR author states they unpacked the rendered ConfigMap and parsed `k8s-outposts.yaml` separately to confirm it's still valid YAML with 74 entries; I independently verified via a comment-only diff filter that no non-comment line changed, which is the strongest possible guarantee here (a parse check confirms validity, but the line-level diff filter confirms *nothing structural moved at all*). ## Recommendation Looks reasonable — no blocking issues; comments above are optional.

k.renner merged commit 2080260212 into master

2026-08-28 05:21:48 +00:00

k.renner referenced this issue from a commit

2026-08-28 05:21:50 +00:00

Merge pull request 'docs(authentik): trim the blueprint comments, keep every ordering rule' (#688) from trim-comments-authentik into master

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: konairius/homelab#688