Dominik Schön
bbbe4f8985
- New patterns/ directory with 7 initial failure-mode patterns (PAT-001..007) - skill-impact.md audit trail for skill modifications - _template.md for future pattern creation - index.md updated with Patterns section - log.md entry for this change - Inspired by arXiv:2608.27454 (WikiSkill)
59 lines
1.9 KiB
Markdown
59 lines
1.9 KiB
Markdown
---
|
|
pattern_id: PAT-002
|
|
title: "Traefik `reload` unreliable after conf.d edits — use `restart`"
|
|
category: infrastructure
|
|
severity: medium
|
|
status: active
|
|
first_observed: 2026-07
|
|
last_updated: 2026-08-30
|
|
related_systems: [proxmox-cluster, rke2-kubernetes]
|
|
related_solution_docs:
|
|
- docs/solutions/bug-fixes/2026-07-26-paperless-ingressroute-hostname-fix.md
|
|
related_skills: []
|
|
---
|
|
|
|
# Traefik `reload` unreliable after conf.d edits — use `restart`
|
|
|
|
## Symptom
|
|
|
|
After modifying Traefik configuration files (especially dynamic config in `conf.d/`),
|
|
issuing a `reload` signal (SIGHUP) does not reliably pick up the changes. The old
|
|
configuration remains active, leading to stale ingress routes, incorrect routing,
|
|
or 404 errors.
|
|
|
|
## Root Cause
|
|
|
|
Traefik's hot-reload mechanism for file-based dynamic configuration can silently fail to
|
|
detect changes, especially when:
|
|
- Files are edited in-place (atomic rename not used)
|
|
- The file watcher misses events on certain filesystems (e.g., overlayfs, NFS)
|
|
- rsync is used without `--inplace` (creates temp file + rename, which the watcher may miss)
|
|
|
|
## Mitigation
|
|
|
|
Use `restart` instead of `reload` for Traefik container/service after conf.d edits:
|
|
```bash
|
|
# Instead of: docker kill -s HUP traefik (or systemctl reload traefik)
|
|
# Use:
|
|
docker compose restart traefik
|
|
# or: systemctl restart traefik
|
|
```
|
|
|
|
Additionally, when syncing config files via rsync, use `--inplace` to avoid
|
|
temp-file-rename patterns that confuse file watchers:
|
|
```bash
|
|
rsync --inplace -av ./conf.d/ /etc/traefik/conf.d/
|
|
```
|
|
|
|
## Prevention
|
|
|
|
- Always use `restart` (not `reload`) after Traefik config changes in the Traefik CT (99999)
|
|
- Use `rsync --inplace` when pushing config files to the Traefik host
|
|
- Document this in deployment runbooks
|
|
|
|
## Evidence
|
|
|
|
- Observed during Paperless v3 IngressRoute hostname fix (Jul 2026)
|
|
- Traefik runs in CT99999, conf.d directory
|
|
- MEMORY.md entry: "Traefik CT99999: `reload` unreliable after conf.d edits. Use `restart` or `rsync --inplace`."
|