amadan
README: operator note for v0.22.0 (Availability, replica placements)
What an operator should know before rolling v0.22.0 (#409, #417, #418): - roll the boxes and the console together; - console rollback is safe, and the Errors tab shows fewer rows now that platform lines have moved to Availability; - long polls will show a standing "gave up waiting" row, and quick visitor exits are no longer filed; - tunnelled failures are filed once; - against an old console, `carlos availability` prints a generic "not found" error, and replica flags are silently ignored; - #409 adds two registry columns on each box, additively; - create no replica until every box has rolled. Fact-checked by a Sonnet copy review and a Fable review; all amendments applied.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+52
−0
README.md+52 −0
CI passed — run details
diff --git a/README.md b/README.md| index faa6765c0..c01f67ea8 100644 |
| --- a/README.md |
| +++ b/README.md |
| @@ -313,6 +313,58 @@ route's host rather than the whole app. |
| deployment's policy before this rolls there, since a narrower grant is |
| exactly what would trip it. |
| +### Availability, and why the edge had no answer (2026-09-24) |
| + |
| +This release moves every 502, 503 and 504 the edge sees from the Errors |
| +tab to a new Availability tab, grouped by cause (errors spec |
| +`2026-09-07-errors-and-analytics-design.md` §11), and adds replica |
| +placements (#409). |
| + |
| +- roll the boxes and the console together. the boxes record causes and the |
| + console shows them. the console alone gives the Availability tab, and |
| + 502s already stored regroup there under "cause not recorded"; until the |
| + boxes roll, new 502s land there too. boxes alone, with an old console, |
| + file new records the old console lists on Errors, one row per cause, |
| + named like "502 · the instance refused the connection". |
| +- rolling the console back is safe. nothing in the bucket is rewritten; |
| + the regrouping happens on read. |
| +- the Errors tab and `carlos errors` show fewer rows. edge 502/503/504 and |
| + every platform-stream line (failed wakes, exits, sidecar restarts) are |
| + on Availability now. anyone watching Errors for wake failures should |
| + watch Availability instead. |
| +- a request whose visitor gives up after waiting five seconds or more, |
| + before the instance has sent response headers, is now filed as an |
| + outage, as "the visitor gave up waiting for the instance". the five |
| + seconds count from when the edge received the request, so on a |
| + hibernating route they include the wake. an endpoint that holds its |
| + response headers longer than that by design, like a long poll, will |
| + show a standing row for it. that row is expected; it is not a |
| + regression. a slow export that sends its headers straight away does |
| + not. |
| +- a visitor who leaves within five seconds is no longer filed at all. |
| + previously those were filed as a 502 on whatever path they were |
| + loading, so expect fewer single-count 502s on static assets. |
| +- on a route this box proxies over a tunnel or to a fleet, the front box |
| + now files only its own hop failures. the box serving the app files the |
| + rest, so a tunnelled 500 is filed once, not twice. two edges follow from |
| + that: a visitor who leaves after five seconds can be filed as |
| + "gave up waiting" on both boxes, and a far agent whose status store |
| + failed to open files nothing, which the front box no longer covers. |
| +- a new CLI against a console that has not been updated: |
| + - `carlos availability` fails with `not found: check --account and |
| + --app, and that your token's address is a member`. until the |
| + console rolls, that message means the console predates the |
| + command, not that the app or your membership is missing. |
| + - `carlos instances create --role replica` is silently ignored by an |
| + old console, which creates an ordinary home instance in that region |
| + instead. update the console before creating a replica. |
| +- replica placements add two registry columns (`routes.replicas`, |
| + `routes.replica`) on each box's start, by an idempotent `ALTER TABLE`. |
| + there is no migration to run, and a box rolled back keeps two unused |
| + columns harmlessly. do not create a replica until every box is on this |
| + release: only this release's DNS steering leaves replicas out of |
| + latency routing. |
| + |
| ## App config & secrets |
| Per-app config lives in the deployment bucket |