Repository navigation
docs(instances): guide to adding a remote-provisioner lane - #10415
Conversation
The `remote_provisioners` CPP seam shipped with a spec note that says what the seam is, and no page that says how to use it. A contributor who wants a second way to create a remote instance — a container task, a managed dev-environment service, a fleet API — has to read `platform/interfaces.py`, `cloud/launch_job.py`, `handlers_cloud.py` and `remoteProvisionerRenderers.tsx` to find out that the answer is "a descriptor and a five-method engine, and nothing else". New guide `docs/guides/adding-a-remote-provisioner.md`, in five parts: how a remote instance is reached today (registry, one transport-neutral tunnel manager, the two entry points into the same registry), the three interfaces as per-field tables, the lanes that exist today and how each relates to the seam, the step-by-step for adding one, and two worked examples. Three things the guide is deliberate about, because each is a mistake the code makes expensive: - The four launch step KEYS are fixed and only their labels are relabelable, because `run_launch` branches its rollback on `provision` having been the step that failed. - `teardown` returns True only when the resource is CONFIRMED gone, and `register` must raise when the registry write fails — mirroring `RealLaunchEngine.register`, which exists because ignoring `register_instance`'s best-effort None marked a launch done while the user paid for an invisible machine. - The Fargate work is a DRAFT RFC with an empty `implementation-prs` list, and the crew bundle builder (#9213, merged) and crew container runtime (#9223, open) are the bundle and image side: neither implements `LaunchEngine` nor writes to the instances registry. Verified by searching the `aws_control` app on main and #9223's diff for `LaunchEngine`, `register_instance` and `InstancesRegistry` — zero hits in both. Cross-links: the `remote_provisioners` note in platform-context.md and the `GET /api/cloud/provisioners` row in instances.md now point at the guide, and the guide is registered in the guides index so reachability holds. Citations are `path::Symbol`, not `path:LINE`: docs-lint's `line-ref` check fails a line citation anywhere in prose, since it rots on the next refactor with nothing going red. Verification: `scripts/docs_lint.py --test` then `scripts/docs-lint.sh` pass with no finding naming the new file; brand gate passes with BRAND_BASE_REF at the merge base; the one mermaid block parses under `mermaid.parse`.
Design Review (Fable 5) — ✅ PASSDesign-level review of Verified the guide's load-bearing claims against Design-Verdict: PASS Accurate, code-verified contract documentation at the right layer (guide, not spec-note bloat), solving a real discoverability gap with proportionate scope. Suggestions
[DESIGN-REVIEWED] 25d9d3a |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
GPT 5.6 raised three findings on the guide and all three are right against the
code. Each was checked at the call site before changing a word.
**`teardown` never sees what `provision` returned.** `run_launch` generates
`tag` before `preflight` and passes it to both `provision` and `teardown`;
`provision`'s return value goes to `job.instance_id`, and from there to
`begin_signin` and `register` only. The guide said `provision` must "return the
identity `teardown` can act on", which points a new lane at the wrong handle: a
resource findable only by that identity is one rollback cannot delete. Corrected
to "the identity `register` accepts", with the real requirement stated — tag the
resource with `tag`, and make `teardown` idempotent, because rollback can call it
for a `tag` whose `provision` created nothing.
**A raise out of `begin_signin` is not rolled back.** Rollback is scoped to
`job.step("provision").state == "failed"`, on the reasoning that a later failure
means the machine exists and `register` has already named it for recovery. That
reasoning holds for a `register` failure and does not hold for `begin_signin`,
which runs before `register`: the machine exists, nothing rolls it back, and
nothing registered it either. New section B subsection names this window, and the
`begin_signin` row now says not to raise for a sign-in that merely did not
complete — return a handle whose `wait` returns `False` and the launch reaches
`register`, which is the recoverable outcome. The cancel path has no such gap
(`stack_may_exist` covers any provision step past `pending`), so the guide says
that too rather than implying rollback is generally absent.
**The `aws_ec2` reservation is frontend-enforced only.** The guide claimed
`test_remote_provisioner_seam.py` asserts a descriptor cannot claim `aws_ec2`.
It does not, and nothing on the backend rejects a second descriptor under that
id — `_provisioners()` filters blank ids and does not deduplicate, so a duplicate
row would leave `api_cloud_launch_create` resolving whichever it reaches first.
What IS enforced is `registerRemoteProvisionerRenderer` refusing the built-in
KIND. Both descriptor rows and the test section now say which half is a
convention and which is a check.
The test section also now describes what the two suites actually assert (the
`Two` fixture in the seam test is the composition shape to copy) and adds the two
cases a new lane must cover itself: `teardown` from `tag` alone, and a failed
sign-in leaving the instance registered.
Verification: `scripts/docs-lint.sh` passes with no finding naming the file, the
brand gate passes at the merge base, and the mermaid block still parses. The
in-flight CI run on the previous head was cancelled before this edit — backend
shards on a docs diff carry no signal for a commit that is being replaced.
bolichen97
left a comment
There was a problem hiding this comment.
Docs only. Claims checked against code at call sites, review corrections (tag as teardown handle, begin_signin rollback window, aws_ec2 claim enforced only client-side) incorporated. docs-lint and brand gate pass.
…v#10415) * docs(instances): guide to adding a remote-provisioner lane The `remote_provisioners` CPP seam shipped with a spec note that says what the seam is, and no page that says how to use it. A contributor who wants a second way to create a remote instance — a container task, a managed dev-environment service, a fleet API — has to read `platform/interfaces.py`, `cloud/launch_job.py`, `handlers_cloud.py` and `remoteProvisionerRenderers.tsx` to find out that the answer is "a descriptor and a five-method engine, and nothing else". New guide `docs/guides/adding-a-remote-provisioner.md`, in five parts: how a remote instance is reached today (registry, one transport-neutral tunnel manager, the two entry points into the same registry), the three interfaces as per-field tables, the lanes that exist today and how each relates to the seam, the step-by-step for adding one, and two worked examples. Three things the guide is deliberate about, because each is a mistake the code makes expensive: - The four launch step KEYS are fixed and only their labels are relabelable, because `run_launch` branches its rollback on `provision` having been the step that failed. - `teardown` returns True only when the resource is CONFIRMED gone, and `register` must raise when the registry write fails — mirroring `RealLaunchEngine.register`, which exists because ignoring `register_instance`'s best-effort None marked a launch done while the user paid for an invisible machine. - The Fargate work is a DRAFT RFC with an empty `implementation-prs` list, and the crew bundle builder (kirodotdev#9213, merged) and crew container runtime (kirodotdev#9223, open) are the bundle and image side: neither implements `LaunchEngine` nor writes to the instances registry. Verified by searching the `aws_control` app on main and kirodotdev#9223's diff for `LaunchEngine`, `register_instance` and `InstancesRegistry` — zero hits in both. Cross-links: the `remote_provisioners` note in platform-context.md and the `GET /api/cloud/provisioners` row in instances.md now point at the guide, and the guide is registered in the guides index so reachability holds. Citations are `path::Symbol`, not `path:LINE`: docs-lint's `line-ref` check fails a line citation anywhere in prose, since it rots on the next refactor with nothing going red. Verification: `scripts/docs_lint.py --test` then `scripts/docs-lint.sh` pass with no finding naming the new file; brand gate passes with BRAND_BASE_REF at the merge base; the one mermaid block parses under `mermaid.parse`. * docs(instances): correct three engine-contract claims in the lane guide GPT 5.6 raised three findings on the guide and all three are right against the code. Each was checked at the call site before changing a word. **`teardown` never sees what `provision` returned.** `run_launch` generates `tag` before `preflight` and passes it to both `provision` and `teardown`; `provision`'s return value goes to `job.instance_id`, and from there to `begin_signin` and `register` only. The guide said `provision` must "return the identity `teardown` can act on", which points a new lane at the wrong handle: a resource findable only by that identity is one rollback cannot delete. Corrected to "the identity `register` accepts", with the real requirement stated — tag the resource with `tag`, and make `teardown` idempotent, because rollback can call it for a `tag` whose `provision` created nothing. **A raise out of `begin_signin` is not rolled back.** Rollback is scoped to `job.step("provision").state == "failed"`, on the reasoning that a later failure means the machine exists and `register` has already named it for recovery. That reasoning holds for a `register` failure and does not hold for `begin_signin`, which runs before `register`: the machine exists, nothing rolls it back, and nothing registered it either. New section B subsection names this window, and the `begin_signin` row now says not to raise for a sign-in that merely did not complete — return a handle whose `wait` returns `False` and the launch reaches `register`, which is the recoverable outcome. The cancel path has no such gap (`stack_may_exist` covers any provision step past `pending`), so the guide says that too rather than implying rollback is generally absent. **The `aws_ec2` reservation is frontend-enforced only.** The guide claimed `test_remote_provisioner_seam.py` asserts a descriptor cannot claim `aws_ec2`. It does not, and nothing on the backend rejects a second descriptor under that id — `_provisioners()` filters blank ids and does not deduplicate, so a duplicate row would leave `api_cloud_launch_create` resolving whichever it reaches first. What IS enforced is `registerRemoteProvisionerRenderer` refusing the built-in KIND. Both descriptor rows and the test section now say which half is a convention and which is a check. The test section also now describes what the two suites actually assert (the `Two` fixture in the seam test is the composition shape to copy) and adds the two cases a new lane must cover itself: `teardown` from `tag` alone, and a failed sign-in leaving the instance registered. Verification: `scripts/docs-lint.sh` passes with no finding naming the file, the brand gate passes at the merge base, and the mermaid block still parses. The in-flight CI run on the previous head was cancelled before this edit — backend shards on a docs diff carry no signal for a commit that is being replaced. --------- Co-authored-by: Joe Guo <zejiangg@amazon.com>
Problem / Motivation
The
remote_provisionersCPP seam shipped with a spec note that says what the seam is, and no page that says how to use it.A contributor who wants a second way to create a remote instance — a container task, a managed dev-environment service, a fleet API — has to read
src/kiro_crew/platform/interfaces.py,src/kiro_crew/cloud/launch_job.py,src/kiro_crew/dashboard/handlers_cloud.pyandwebsite/src/components/remoteProvisionerRenderers.tsxbefore learning that the answer is "a descriptor and a five-method engine, and nothing else". Nothing tells them which parts of the launch machinery they inherit for free, which four identifiers they must not rename, which handle rollback actually gets, or which of the two transports to register with.Why it matters
The seam's whole point is that an edition does not reimplement the launch loop. A contributor who does not know that writes their own cancel handling, rollback and orphan reaping — and gets each of them subtly wrong, because every one of those paths exists to stop a user paying for a machine they cannot see.
Two of those mistakes are already recorded in the code as things that happened:
RealLaunchEngine.registerraises on failure because ignoringregister_instance's best-effortNonemarked a launchdonewhile the crew was absent from the dashboard — the user was told setup succeeded and left paying for an instance that never appeared.teardownconfirms rather than trusting an accepted delete, because a stack can reachDELETE_FAILEDand reporting "Removed" tells the user their billing stopped when it did not.Both are guarantees a new lane owes, and neither is discoverable without reading the built-in engine.
What changed (motivation → approach → change)
Goal: one page a contributor reads end to end before writing a lane, with every claim checked against the code rather than against the spec note.
Approach: current design → interfaces → existing lanes → procedure → worked examples, so a reader who only wants the field tables stops at section B and a reader who wants a shape to copy jumps to section E. Rejected alternative: extending the
remote_provisionersnote inplatform-context.md. A spec note states the contract; it is the wrong genre for a procedure, and that note is already the longest on the page.Change: new
docs/guides/adding-a-remote-provisioner.md(230 lines), plus three cross-links.Four things the guide is deliberate about, because each is a mistake the code makes expensive:
run_launchrolls back only whenprovisionis the step that failed. Rename a key and that branch stops matching.step_labelsexists so a lane that does not create an EC2 instance is not described as one.tagis the teardown handle, and rollback has one blind spot.teardownreceivestag, neverprovision's return, so a resource findable only by that return is one rollback cannot delete. And rollback is scoped to aprovision-step failure — which means a raise out ofbegin_signinleaves a machine that is neither rolled back nor registered. Both are stated as requirements on the engine, with the reasoning.size_key,profileandregionare generic wires, not AWS fields.LaunchJobStore.createvalidatessize_keyagainstsizes.pyonly for the built-in id, because validating every lane against the EC2 ladder would refuse every non-EC2 launch.status: draft, emptyimplementation-prs). The crew bundle builder (feat(aws-control): curate a crew into a portable bundle #9213, merged) and the crew container runtime (feat(aws-control): the crew container image and its runtime #9223, open) are the bundle and image side — they produce something a lane could run, and are easy to mistake for the lane. The guide says so plainly.Also stated, because each is a boundary a new lane will otherwise walk into: the stop/start/delete routes under
/api/cloud/{tag}/...are EC2-specific and a lane contributes its own throughcontribute_routes; and nocapabilities.remote_provisionersgovernance scope exists yet, so a lane needing one is adding that work, not inheriting it.Citations are
path::Symbol, notpath:LINE. docs-lint'sline-refcheck fails a line citation anywhere in prose — it rots on the next refactor with nothing going red. Cross-links added to theremote_provisionersnote inplatform-context.mdand theGET /api/cloud/provisionersrow ininstances.md; the guide is registered indocs/guides/README.mdso the reachability check holds.No feature-map row:
docs/feature-map/README.mdindexes user-facing dashboard features, and this PR adds no page, route or handler.Review round: three corrections in commit 2
GPT 5.6 raised three findings on the first commit. All three were right against the code, and each was checked at the call site before being changed:
provision"returns the identityteardowncan act on"run_launchpassestagtoteardown;provision's return goes tojob.instance_id→begin_signinandregisteronlyregisteraccepts", plus the real requirement: tag the resource withtag, and maketeardownidempotentbegin_signinbypasses rollbackjob.step("provision").state == "failed"; a signin-step raise leaves that stepdone, so nothing rolls back andregisternever ranbegin_signinmust not raise for an incomplete sign-inaws_ec2"test_remote_provisioner_seam.pyasserts no such thing, and_provisioners()does not deduplicate. The enforced half isregisterRemoteProvisionerRendererrefusing the built-in KINDThe test section also now describes what the two suites actually assert, and names the two cases a new lane must cover itself:
teardownfromtagalone, and a failed sign-in leaving the instance registered.Design Review returned PASS with no advisory concerns; Opus 4.8 returned no findings.
Tests
N/A — documentation only, no code changed. The enforcement this PR is subject to is
docs-lint, a CI gate rather than a test file: link resolution, index reachability,path-existson every backticked repo-anchored path, and theline-refand beyond-EOF citation checks.Manual verification
Every factual claim was read out of the tree on this branch's base (
b862ddd7f9) before being written:CONNECTION_METHODS == ("ssh", "ssm"), the per-transport field split and theInstance.validatebranch, insrc/kiro_crew/instances/registry.py.SshTunnelManagerbranching onconnection_methodto build either anssh -N -Lor anaws ssm start-sessionargv, insrc/kiro_crew/instances/ssh_tunnel_manager.py.api_instances_adddefaultingconnection_methodto"ssh";register_instancehard-coding"ssm"and updating in place on re-launch.LaunchEnginemethods; the four step keys;run_launchscoping rollback to aprovisionfailure;registerrunning under the step keyedconnect, not aregisterstep;_new_tag()running beforepreflightandteardownreceiving onlytag._engine's degraded-seam fallback reaching the built-in engine for the built-in id only;api_cloud_launch_createresolving the engine before the job file exists.BUILTIN_REMOTE_PROVISIONER_KINDS == ['aws_ec2']and the renderer refusal, inremoteProvisionerRenderers.tsx; and the absence of any equivalent backend check.grep -rn 'LaunchEngine|InstancesRegistry|register_instance' src/kiro_crew/apps/builtins/aws_control/returns nothing onmain, and the same pattern overgh pr diff 9223returns nothing. Neither the bundle builder nor the container runtime touches the seam or the registry.Gates run locally on the current head:
docs-lintreports no finding naming the new file. Two AWS API names (RunTask,StopTask) were un-backticked after the first run, which had reported one as a report-onlydead-identifier— an AWS operation is not a first-party identifier, and leaving it would have added noise to a gate that is otherwise silent on this diff.The single mermaid block was parsed with
mermaid.parse()(mermaid 11 under jsdom, node 24) rather than eyeballed:blocks: 1 / block 1: ok. GitHub renders mermaid server-side, so a syntax error would ship as a broken diagram with nothing going red.Screenshots / video
N/A — no user-visible UI change. Documentation under
docs/, which is not shipped in the dashboard.Related Issues
None. Follow-on documentation for the
remote_provisionersseam.Checklist
docs-lintand the brand gate pass