jschoubben
03266fd4a2
Found by the forge failing to start. I had put `restart-on` on nine containers so they would pick up a rotated credential; it belongs to a service, and the host refused the whole declaration. Removing it fixes the modules and leaves the reason I reached for it. The mechanism is written against exactly this, in the host's own words: a running service does not re-read its configuration, so replace the file, find it already running, do nothing, and the machine keeps behaving as before while every check passes. Every word of that applies to a container, and nearly everything the mesh runs is one. The cost is concrete. Rotation replaces the file and tells the provider to accept the new credential. A provider reconciles, so it takes it. A consumer is usually a container, so it does not — and the two ends hold different passwords, which is the fault ADR 0001 records costing two days. The test that proves rotation works uses a consumer that reads the file on each attempt, so it does not meet this. Two things a fix has to keep: it stays declared state rather than a command, because the link may not carry an action; and where an env-file changed, the honest verb is recreate rather than restart, because a container's environment is fixed at creation.
04-ISSUES
The front door for "something is wrong" at the level of the mesh's design or governance. Diagnosis happens here, where the whole mesh is in view; the fix lands in the owning code repository.
What belongs here
| Belongs here | Belongs in the knowledge base |
|---|---|
| The design permits a failure to be silent | How to fix one occurrence of it |
| A documented rule is enforced by nothing | A command that works around it |
| A stated invariant is false in practice | A node-specific quirk |
| The owner is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known |
The knowledge base already holds the operational record and is indexed on symptoms. This folder is not a second copy of it. An issue here is a question HQ must answer; an entry there is an incident someone must clear. An issue whose answer is a general lesson belongs in both.
Structure
NNN-short-name/
00-report.md the symptom as observed, with the evidence; status in frontmatter
01-diagnosis.md the investigation trail, dated, including what was ruled out
Frontmatter, on 00-report.md
---
status: open | diagnosing | located | resolved | wontfix
opened: YYYY-MM-DD
located-in: [] # owning repo(s) or module(s), filled by diagnosis
fixed-by: # pull request or commit reference, filled at resolution
amended-design: # design doc path, when the root cause was a design gap
---
Rules
- Anyone may open an issue. No localisation is required to report one.
- The full flow is playbook
00-META/process/03-issues.md. - Closed issues are never deleted — they are the mesh's symptom-to-component memory.
wontfixis legitimate and requires a sentence saying why.