Skip to content

docs(smaug): correct stale rule counts, golem's pass and runbook residue - #1497

Open
Gerrrt wants to merge 2 commits into
mainfrom
docs/smaug-audit-staleness
Open

Gerrrt wants to merge 2 commits into
mainfrom
docs/smaug-audit-staleness

Conversation

@Gerrrt

@Gerrrt Gerrrt commented Nov 14, 2026

Copy link
Copy Markdown
Owner

What changed

Docs only. Corrects the smaug text that a read-only audit on 2026-11-13 found stale or self-contradictory. Nothing on the running lab changes.

  • golem's 2049 pass (Allow NFS from golem to smaug, 2026-10-03) was missing from three of the places that list smaug's inbound rules. It is now in build-the-nas.md §0.5's table, in the stacks/media README's What is published table and consumer list, and in security.md's CasaBonita paragraph, with its residual.
  • Rule counts that disagreed with network.md's nine: security.md said "six" and now names no count; architecture.md said "the four inbound rules" and now points at network.md.
  • build-the-nas.md:
    • §6.4's SMART check reads the port, not the letter (ADR-0066), and no longer puts the Exos on the MegaRAID (ADR-0052).
    • §6.7's status block records steps 1–3 as read on smaug. Step 4's check-versions reading is still open.
    • §7 names ether17 on the CRS326 instead of port 15 on neo.
    • §8 no longer calls SMART or §6.8 "not yet running".
    • Every "two curl lines" now points at §6's smaug-fetch.sh block.
  • stacks/media compose header and README:
    • The deploy is a fetch from one pinned commit, not "from main".
    • Port 22 is live since 2026-09-19, not inert.

Why

A read-only audit of smaug on 2026-11-13 found these against the box: the cron jobs, the done sections, the switch port and the export to golem all exist, and the docs said otherwise or left them out. network.md is the authority for the rule count. Refs #616.

Blast radius

None at runtime: prose and a YAML comment. A wrong sentence here would misdirect the next person running build-the-nas.md.

  • No change to network segmentation or firewall rules
  • No new port published to a VLAN that could not already reach the service
  • No credential added outside secrets/*.sops.yaml

Verification

  • python3 scripts/check_docs.py: docs OK — 161 Prometheus + 21 Loki rules, 8 dashboards, 156 panels, 13 assertions

  • ./scripts/lint.sh: passed, but 14 checks were skipped and not run: yamllint, markdownlint-cli2, shellcheck, ruff ×2, actionlint, zizmor, packer ×2, tofu ×3, ansible-lint, editorconfig-checker. This checkout has no Docker daemon or pipx; CI runs them with --require-all.

  • make validate was not run: make is not installed where this was authored.

  • git diff --check: clean.

  • make validate passes

  • Deployed to the lab and confirmed working (not applicable: docs only)

  • Docs updated (docs/, service README, or docs/roadmap.md)

🤖 Generated with Claude Code

Copilot AI balanced review requested due to automatic review settings November 14, 2026 00:19
@Gerrrt
Gerrrt enabled auto-merge (squash) November 14, 2026 00:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The runbook still presents a completed verification as outstanding and needs to include the September completion evidence while distinguishing it from the November local re-audit.

1 open issue
What changed in this PR

This documentation-only PR aligns smaug’s NAS and media-stack guidance with the recorded deployment and November audit. It changes no runtime configuration.

Changes:

  • Adds golem’s NFS access and its security implications to the inbound-access documentation.
  • Corrects stale rule counts, SMART guidance, switch-port references, and collector status.
  • Documents pinned-commit deployment through smaug-fetch.sh and the existing SSH backup access.
File Description
stacks/​media/​README.md Updates deployment guidance, inbound access, and NFS consumers.
stacks/​media/​compose.yaml Corrects deployment instructions in the header comment only.
docs/​security.md Adds golem’s NFS trust and recovery limits; removes a stale rule count.
docs/​runbooks/​build-the-nas.md Refreshes NAS procedures, hardware references, and completion notes.
docs/​architecture.md Points readers to the authoritative current inbound-rule count.

Review effort: Balanced

Comment thread docs/runbooks/build-the-nas.md Outdated
Comment on lines +1782 to +1787
> **Steps 1–3 done, read on `smaug` 2026-11-13; step 4 not yet read.** The
> cron job `homelab truenas-version (#616)` exists at 08:40 daily, and
> `truenas-version.prom` carries `truenas_version_info` for `25.10.7`, with
> `node_textfile_scrape_error` 0 on the exporter. The `check-versions`
> reading from the monitoring host still goes here, and
> [#616](https://github.com/Gerrrt/HomeLab/issues/616) closes on it.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

6.7 now records the 2026-09-23 completion (both smaug PASS lines, linked to #616 closing comment) and keeps the 2026-11-13 local re-read as a separate note that says check-versions was not re-run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants