amadan
docs: the instance service role provisions instances, it does not just read them (#373)
`carlos services --role instance` reaches POST/GET/PATCH/DELETE on an app's instances and the four move doors (authcli.go, pinned in svcroutes_test.go), but cli.md described it as "what a box-side reader wants". A session designing a hosted suite that mints one instance per team read that, ruled the credential out, built an operator-drained queue instead, and filed the missing machine credential as a product gap (amadan carlos/platform#4) — two weeks after PR #227 shipped exactly it. Also names the one door closed to every role, since it is the half that makes the rest safe to hand a server: enable writes the manifest that bounds what the credential may then create, so a person does it once. Claude-Session: https://claude.ai/code/session_01DqT65F1iMwc8NjVG9r8Tr7
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 file changed,
+14
−7
docs/site/cli.md+14 −7
CI passed — run details
diff --git a/docs/site/cli.md b/docs/site/cli.md| index ccac0200e..26f3a0bde 100644 |
| --- a/docs/site/cli.md |
| +++ b/docs/site/cli.md |
| @@ -575,18 +575,25 @@ stops it. |
| ### carlos services |
| Credentials a server holds rather than a person: a CI job that ships, a |
| -sidecar that reads instances. Reach is fixed at mint, so adding you to |
| -another account later does not widen it, and it has its own rate-limit budget. |
| +sidecar that reads instances, an app that mints an instance per customer at |
| +signup. Reach is fixed at mint, so adding you to another account later does |
| +not widen it, and it has its own rate-limit budget. |
| ```sh |
| carlos services create --role publish --app hello ci-shipper |
| ``` |
| -Pick the narrowest role that works. `publish` ships releases, `instance` is |
| -what a box-side reader wants, `operate` administers, and `admin` includes |
| -`store grant`, which mints a path-scoped IAM user; treat that one as a real |
| -handover. `--app` binds the credential to one app, which also means it cannot |
| -create apps. |
| +Pick the narrowest role that works. `publish` ships releases; `instance` |
| +provisions an app's instances — create, delete, upstreams and moves, plus its |
| +domains and logs — which is the role a self-serve signup path wants; `operate` |
| +administers; and `admin` includes `store grant`, which mints a path-scoped IAM |
| +user, so treat that one as a real handover. `--app` binds the credential to |
| +one app, which also means it cannot create apps. |
| + |
| +One door stays shut to every role: `carlos instances enable`, which writes the |
| +manifest bounding which domain, pool and regions an instance may be created |
| +in. A person enables the app once and the credential provisions inside those |
| +bounds afterwards. |
| The secret prints once, same as a fleet token, and the same distinction |
| applies at the other end: `rotate` refuses the credential's next call with |