feat: patterns/ directory + skill-impact tracker (WikiSkill-inspired)
- 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)
This commit is contained in:
@@ -0,0 +1,58 @@
|
||||
---
|
||||
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`."
|
||||
Reference in New Issue
Block a user