Skip to content

docs(instances): guide to adding a remote-provisioner lane - #10415

Merged
bolichen97 merged 2 commits into
mainfrom
docs/remote-provisioner-guide
Sep 12, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
docs/remote-provisioner-guide

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

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 src/kiro_crew/platform/interfaces.py, src/kiro_crew/cloud/launch_job.py, src/kiro_crew/dashboard/handlers_cloud.py and website/src/components/remoteProvisionerRenderers.tsx before 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.register raises on failure because ignoring register_instance's best-effort None marked a launch done while the crew was absent from the dashboard — the user was told setup succeeded and left paying for an instance that never appeared.
  • teardown confirms rather than trusting an accepted delete, because a stack can reach DELETE_FAILED and 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_provisioners note in platform-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:

  1. The four launch step KEYS are fixed; only their labels are relabelable. run_launch rolls back only when provision is the step that failed. Rename a key and that branch stops matching. step_labels exists so a lane that does not create an EC2 instance is not described as one.
  2. tag is the teardown handle, and rollback has one blind spot. teardown receives tag, never provision's return, so a resource findable only by that return is one rollback cannot delete. And rollback is scoped to a provision-step failure — which means a raise out of begin_signin leaves a machine that is neither rolled back nor registered. Both are stated as requirements on the engine, with the reasoning.
  3. size_key, profile and region are generic wires, not AWS fields. LaunchJobStore.create validates size_key against sizes.py only for the built-in id, because validating every lane against the EC2 ladder would refuse every non-EC2 launch.
  4. What is NOT a provisioner lane. The Fargate work is a draft RFC (status: draft, empty implementation-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 through contribute_routes; and no capabilities.remote_provisioners governance scope exists yet, so a lane needing one is adding that work, not inheriting it.

Citations are path::Symbol, not path:LINE. docs-lint's line-ref check fails a line citation anywhere in prose — it rots on the next refactor with nothing going red. Cross-links added to the remote_provisioners note in platform-context.md and the GET /api/cloud/provisioners row in instances.md; the guide is registered in docs/guides/README.md so the reachability check holds.

No feature-map row: docs/feature-map/README.md indexes 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:

Finding The code Fix
provision "returns the identity teardown can act on" run_launch passes tag to teardown; provision's return goes to job.instance_id → begin_signin and register only Corrected to "the identity register accepts", plus the real requirement: tag the resource with tag, and make teardown idempotent
A raise from begin_signin bypasses rollback Rollback is gated on job.step("provision").state == "failed"; a signin-step raise leaves that step done, so nothing rolls back and register never ran New section B subsection naming the window; begin_signin must not raise for an incomplete sign-in
"a descriptor cannot claim aws_ec2" test_remote_provisioner_seam.py asserts no such thing, and _provisioners() does not deduplicate. The enforced half is registerRemoteProvisionerRenderer refusing the built-in KIND Both descriptor rows and the test section now separate the convention from the check

The test section also now describes what the two suites actually assert, and names the two cases a new lane must cover itself: teardown from tag alone, 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-exists on every backticked repo-anchored path, and the line-ref and 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 the Instance.validate branch, in src/kiro_crew/instances/registry.py.
  • SshTunnelManager branching on connection_method to build either an ssh -N -L or an aws ssm start-session argv, in src/kiro_crew/instances/ssh_tunnel_manager.py.
  • api_instances_add defaulting connection_method to "ssh"; register_instance hard-coding "ssm" and updating in place on re-launch.
  • The five LaunchEngine methods; the four step keys; run_launch scoping rollback to a provision failure; register running under the step keyed connect, not a register step; _new_tag() running before preflight and teardown receiving only tag.
  • _engine's degraded-seam fallback reaching the built-in engine for the built-in id only; api_cloud_launch_create resolving the engine before the job file exists.
  • BUILTIN_REMOTE_PROVISIONER_KINDS == ['aws_ec2'] and the renderer refusal, in remoteProvisionerRenderers.tsx; and the absence of any equivalent backend check.
  • The negative claim, checked both ways: grep -rn 'LaunchEngine|InstancesRegistry|register_instance' src/kiro_crew/apps/builtins/aws_control/ returns nothing on main, and the same pattern over gh pr diff 9223 returns nothing. Neither the bundle builder nor the container runtime touches the seam or the registry.

Gates run locally on the current head:

python3 scripts/docs_lint.py --test                       # self-test passed
./scripts/docs-lint.sh                                    # All documentation checks passed
BRAND_BASE_REF=$(git merge-base HEAD origin/main) \
  python3 scripts/check_brand_name.py                     # ✓ no misspellings in added lines
python3 scripts/check_brand_name.py --test                # self-test passed

docs-lint reports 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-only dead-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_provisioners seam.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality — N/A, docs only; docs-lint and the brand gate pass
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

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`.
@iamwhatever
iamwhatever requested review from a team and dwu96 September 12, 2026 20:07
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 12, 2026
@github-actions

github-actions Bot commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 25d9d3a697fb0ecd1ddcb22a5448d504f2498f2a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Verified the guide's load-bearing claims against src/kiro_crew/cloud/launch_job.py: rollback is indeed scoped to a failed provision step (launch_job.py:702), teardown receives only job.tag (launch_job.py:498), register runs under the connect step (launch_job.py:665), and a raise out of begin_signin leaves the machine neither rolled back nor registered — the guide states the code's actual contract accurately, including the parts the code's own comment glosses over.

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

  • The begin_signin-raise window the guide names is a core money-leak gap (run_launch neither rolls back nor registers a machine that exists) — file it as a tracked core issue/fix so the guide's "must not raise" becomes defense-in-depth rather than the only guard.

[DESIGN-REVIEWED] 25d9d3a

@github-actions

github-actions Bot commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 25d9d3a697fb0ecd1ddcb22a5448d504f2498f2a — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 25d9d3a

Verdict parsed from the review's SHA-scoped output markers for commit 25d9d3a697fb0ecd1ddcb22a5448d504f2498f2a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 25d9d3a697fb0ecd1ddcb22a5448d504f2498f2a: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 25d9d3a697fb0ecd1ddcb22a5448d504f2498f2a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 25d9d3a

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 25d9d3a697fb0ecd1ddcb22a5448d504f2498f2a: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 12, 2026
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.
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 12, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bolichen97
bolichen97 merged commit 1393b4d into main Sep 12, 2026
114 of 121 checks passed
@bolichen97
bolichen97 deleted the docs/remote-provisioner-guide branch September 12, 2026 22:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 12, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants