Skip to content
fzymgc-house Cluster Docs

Ship NAS telemetry via a dedicated nas-otel-collector TrueNAS custom app

Date: 2026-06-27 Status: Accepted Decision: hl-wo1m Deciders: sean

Context

Section titled “Context”

The cluster ships telemetry to ClickStack via otel-gateway.fzymgc.house over mTLS, and is sunsetting Grafana/Alloy (epic hl-nlxl). The existing otel-collector Ansible role works on the Firewalla but is deeply coupled to it (otel_collector_user: pi with a getent precondition, unconditional /home/pi/.firewalla/... directories, 19 owner-bound copies). The NAS is a TrueNAS appliance whose Docker is owned by the middleware (app.*).

Decision

Section titled “Decision”

Ship NAS host telemetry via a dedicated nas-otel-collector Ansible role that deploys otelcol-contrib as a TrueNAS custom Docker app (via app.*), reusing the otel config + Vault-PKI-mTLS approach but owning TrueNAS-appropriate delivery. Do not use Alloy, and do not generalize the Firewalla otel-collector role in place.

Rationale

Section titled “Rationale”
  • Alloy is being sunset cluster-wide; new telemetry should target otel → ClickStack directly.
  • A custom app is the appliance-native, upgrade-safe way to run a container on TrueNAS; a raw docker-compose@ unit fights the middleware.
  • Generalizing the Firewalla role proved impractical — its coupling (user pi, /home/pi paths, 19 owner-bound copies) would force risky conditionals through a working deployment.

Alternatives Considered

Section titled “Alternatives Considered”
  • Dedicated nas-otel-collector custom app (chosen): clean isolation; the Firewalla role is untouched.
  • Generalize the existing otel-collector role in place (rejected): Firewalla-coupled; the two delivery mechanisms don’t cohabit cleanly.
  • Alloy (rejected): being sunset cluster-wide.
  • Collector inside the LXC sandbox / netdata tap (rejected): weaker host-metric visibility / less-proven exporter path.

Consequences

Section titled “Consequences”
  • Positive: appliance-native, upgrade-safe; the Firewalla deployment is unaffected; full host metrics via /proc,/sys mounts + journald.
  • Negative: a second otel role to maintain (some config duplication with the Firewalla role).
  • Neutral: the cert is issued from the control node via Vault PKI (re-issue gated on expiry) rather than via a vault-agent sidecar.