Add ADR-0010: keep the resolver on the gateway and filter behind it - #127
Merged
Conversation
ADR-0008 places AdGuard Home on the Winterfell mini PC but does not say how clients reach it. Making it the client-facing resolver would decouple DNS from the default gateway and give the household an independent way to lose name resolution — one that presents as a total outage while every component the family runbook checks is healthy. Records the decision to keep pfSense as the only DHCP-advertised resolver and have Unbound forward to AdGuard, with the public upstreams left in the forwarder list so a dead filter costs filtering rather than connectivity. Rejects advertising AdGuard directly, alone or as a DHCP primary: stub resolvers do not fail over cleanly between advertised servers, so a secondary leaks filtering whenever the primary is merely slow, and both variants would route low-trust VLAN DNS into the sensitive tier against ADR-0008's own reasoning. Accepted costs are recorded: per-client attribution is lost, and the filter now fails silently, which needs a probe that queries AdGuard directly rather than through the fallback. Also corrects the ADR count in the README, which read 8 against 9 files before this change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vt47Sx4BTo6kmizmV31Fnn
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Adds
docs/adr/0010-keep-the-resolver-on-the-gateway.md, recording the decision that pfSense stays the only DHCP-advertised resolver and Unbound forwards to AdGuard Home for filtering. Nothing in the running lab changes — the AdGuard host does not exist yet, and this fixes the topology before it is built.Why
ADR-0008 places AdGuard Home on the Winterfell mini PC but does not say how clients reach it, and that second question carries the risk. Making it the client-facing resolver would decouple DNS from the default gateway and give the household an independent way to lose name resolution — presenting as a total outage while every component the family runbook checks is healthy.
Closes #125. Related: #123 (the family-facing failure mode this removes), #126 (the detection requirement it creates), #122 (the same settle-before-building argument for the rest of ADR-0008's tier).
The ADR also records why the two obvious alternatives were rejected: stub resolvers do not fail over cleanly between advertised servers, so a DHCP secondary leaks filtering whenever the primary is merely slow rather than dead, and both variants would route low-trust VLAN DNS into the sensitive tier against ADR-0008's own reasoning.
Accepted costs are written down rather than glossed: per-client attribution is lost, and the filter now fails silently.
Also corrects the ADR count in the README, which read 8 against 9 files before this change.
Blast radius
Documentation only. No configuration, no manifest, no runtime change.
secrets/*.sops.yamlWorth noting the ADR's own conclusion here: implementing it later adds no inter-VLAN rule, leaving the count at the five ADR-0008 established. The rejected alternatives would each have added one.
Verification
make validatepasses — via CI, all three jobs green on88049e5: Lint, Validate configs, Secret scan. It could not be run in full locally (yamllint: command not foundin the authoring environment, which stopsmake lintbefore the Markdown step); CI has since run the complete target, so that gap was environmental rather than a real one.markdownlint-cli2run directly against the repo's.markdownlint-cli2.yaml:Summary: 0 issues in 0 filesacross all 32 Markdown files. Confirmed independently by CI's Lint job.Worth a reviewer's eye on one judgement call rather than the prose: the forwarder list deliberately keeps the public upstreams alongside AdGuard, so a dead filter degrades to unfiltered resolution instead of none. That does let Unbound's round-trip-time selection send the occasional query past the filter while AdGuard is healthy. The ADR argues the leak is small because locality decides it — sub-millisecond on the LAN against ten to twenty milliseconds to Cloudflare — but it is a real trade and the alternative reading is defensible.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Vt47Sx4BTo6kmizmV31Fnn