Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/system-specs/modules/cloud.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,19 @@ claim that a hostile in-process agent is fully contained.
| `fargate_engine.py` | The `LaunchEngine` for Fargate, not yet reachable through `engine_for`: nothing registers it, and the provisioner id it will need belongs to the change that wires it, because the built-in id gates `size_key` against the EC2 instance ladder and a cpu/memory pair is not on it. Its teardown decides ownership from a task's tags: the `kirocrew:managed` marker is checked as a boolean gate **before** the identifier, so a task whose marker holds anything other than `true` is `UNMARKED` and is never stopped, and identity is then read under the imported `LAUNCH_TAG_KEY`. A running task this launch started but whose launch tag is absent or names another launch is `MISLABELLED`; both it and a running `UNMARKED` task carrying this launch's `startedBy` are REFUSED rather than deleted, and the plan returns `confirmed=False` naming the ARNs, because deleting on a `startedBy` match alone is a guess and reporting `True` would tell the operator their billing stopped when a task may still be running. Neither the marker's key nor its value nor the launch-tag key is spelled here; all three are imported from the modules that own them. |
| `ui.py` / `wizard.py` | Terminal UI + the interactive launch flow. `_deploy_with_progress` runs the blocking deploy on a daemon thread and captures the `aws cloudformation deploy` child via a `proc_sink`, so a Ctrl+C on the main (poll) thread terminates it instead of orphaning it (~1800s). An unknown `--size`/`size_key` on the public `launch()` entrypoint yields a clean rc=1 + message, not an uncaught `KeyError`. Resuming a saved stack (`launch` after `stop`) first calls `_ensure_running_and_ssm_ready` — starts a `stopped` instance and waits for SSM `Online` before sign-in/tunnel (which are SSM-only and would otherwise fail); a `terminated` instance fails clean pointing at `--new`. `last_tag` is persisted (`cfg.save()`) **only after** a deploy confirms healthy — a failed first launch leaves no saved pointer, so the next `launch` retries clean instead of resuming a rolled-back/instance-less stack; `_saved_launch_is_usable` additionally ignores a stale saved tag (from an older build) whose stack is in a `_FAILED_STATES` status or has no instance. |
| `templates/kirocrew-ec2.yaml` | The CloudFormation stack. |
| `templates/kirocrew-fargate-base.yaml` | The account-and-region Fargate stack: the ECS cluster and an egress-only security group with no ingress. One per account and region, shared by every crew's tasks, so deleting one crew's stack cannot delete the cluster its siblings run on. |
| `templates/kirocrew-fargate-crew.yaml` | The per-crew Fargate stack: the execution role (crew-scoped secret read, log write), a policy-less task role, and the log group. Resource names are the ones `identity.py` derives (`kirocrew-crew-<crew>-exec`, `-task`, `/kirocrew/crew/<crew>`) and `taskdef.py` refuses a document that disagrees with, so a rename on either side becomes a launch refusal rather than a mismatch that runs. The task role is created with no policies at all and must never gain `secretsmanager:GetSecretValue` -- the execution role holds that read, scoped to the one crew's secret namespace. |

The two Fargate stacks publish the fields the launch engine's refusal at
`fargate_engine.py` lists, so each has exactly one place to be read from. The
base stack outputs `ClusterName`, `ClusterArn`, `SecurityGroupId`, `SubnetIds`,
`CpuArchitecture`, `Region` and `StackTag`; the crew stack outputs `Crew`,
`ExecutionRoleArn`, `TaskRoleArn`, `LogGroupName`, `SecretNamePrefix` and
`SecretArnPattern`. `SecretArnPattern` is asserted character-for-character
against the policy that grants the read, so an output cannot promise reach the
role does not have. The templates are verified statically and offline by
`test/test_fargate_scaffolding_contract.py`, which calls the `identity.py` and
`taskdef.py` derivation functions rather than restating their strings.

## Provisioning shape

Expand Down
116 changes: 116 additions & 0 deletions src/kiro_crew/cloud/templates/kirocrew-fargate-base.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
AWSTemplateFormatVersion: "2010-09-09"
Description: >-
Shared Fargate scaffolding for Kiro Crew remote crews in the user's own AWS
account: the ECS cluster every crew task runs on and the egress-only security
group they are placed in. One stack per account and region. The per-crew roles
and log group live in kirocrew-fargate-crew.yaml, one stack per crew, so
deleting a crew cannot delete the cluster its siblings run on.

Its outputs are the configuration home for FargateLaunchSpec.placement:
ClusterName, SecurityGroupId and the subnets the operator passed in, plus the
CPU architecture the crew image was built for.

# ---------------------------------------------------------------------------
# Parameters. Networking is taken, never invented: a Fargate task needs a route
# to pull its image, and whether that is a NAT gateway or a public subnet is a
# property of the operator's VPC that this stack cannot discover. Passing the
# subnets in keeps the failure at deploy time with a name attached, instead of a
# task that reaches RUNNING and then cannot pull.
# ---------------------------------------------------------------------------
Parameters:
StackTag:
Type: String
Default: kirocrew
# Mirrors the EC2 lane's cap for the same reason: names derived from this tag
# are bounded by AWS resource-name limits, and a value that passes template
# validation but fails opaquely at resource creation is worse than one
# refused here. An ECS cluster name maxes at 255, so 51 is comfortable.
AllowedPattern: "[a-zA-Z0-9-]{1,51}"
Description: Discovery tag value written as kirocrew:fargate.

VpcId:
Type: AWS::EC2::VPC::Id
Description: VPC the crew tasks are placed in.

SubnetIds:
Type: List<AWS::EC2::Subnet::Id>
Description: >-
Subnets for the tasks' awsvpc network interfaces. Each must be able to
reach the container registry, either through a NAT gateway or as a public
subnet with assignPublicIp enabled at RunTask.

CpuArchitecture:
Type: String
Default: X86_64
# Exactly taskdef.CPU_ARCHITECTURES, upper-case as the ECS API spells it.
# taskdef._refuse_unknown_architecture rejects anything outside that set, so a
# value this stack accepted but the launcher refuses would deploy cleanly and
# then never start a crew. A test compares these values against that frozenset
# by importing it, so a change on either side reds instead.
AllowedValues: [X86_64, ARM64]
Description: >-
Architecture the crew image was built for. It must match the image: a task
whose runtime platform disagrees with its image fails at start.

Resources:
# --- The cluster. Named from the stack tag so a launcher can derive it rather
# than discover it, which is what lets Placement.cluster be stated instead
# of searched for. Naming it explicitly also keeps it out of the account's
# implicit `default` cluster, which runtask.py refuses to assume.
Cluster:
Type: AWS::ECS::Cluster
Properties:
ClusterName: !Sub "kirocrew-crew-${StackTag}"
ClusterSettings:
- Name: containerInsights
Value: disabled
Tags:
- { Key: "kirocrew:managed", Value: "true" }
- { Key: "kirocrew:fargate", Value: !Ref StackTag }

# --- Security group: no ingress at all. The crew's control surface is reached
# outbound-authenticated, so nothing needs to dial in, and an empty ingress
# list is the difference between a crew that is reachable by its owner and
# one that is reachable by the internet. Egress is open so the task can
# pull its image and reach the model endpoint.
TaskSecurityGroup:
Type: AWS::EC2::SecurityGroup
Properties:
GroupDescription: !Sub "Kiro Crew Fargate crews ${StackTag} - egress only, no inbound"
VpcId: !Ref VpcId
SecurityGroupEgress:
- IpProtocol: "-1"
CidrIp: 0.0.0.0/0
Description: Allow all outbound
Tags:
- { Key: "kirocrew:managed", Value: "true" }
- { Key: "kirocrew:fargate", Value: !Ref StackTag }

Outputs:
ClusterName:
Description: ECS cluster name for FargateLaunchSpec.placement.cluster.
Value: !Ref Cluster
ClusterArn:
Description: ECS cluster ARN.
Value: !GetAtt Cluster.Arn
SecurityGroupId:
Description: Security group id for FargateLaunchSpec.placement.security_groups.
Value: !Ref TaskSecurityGroup
SubnetIds:
Description: >-
Subnets for FargateLaunchSpec.placement.subnets, echoed back so the launch
spec reads every placement field from stack outputs rather than half from a
stack and half from whatever the operator typed.
Value: !Join [",", !Ref SubnetIds]
CpuArchitecture:
Description: >-
Architecture for FargateLaunchSpec.cpu_architecture, echoed back for the
same reason as SubnetIds: every launch-spec field is read from a stack
output rather than half from a stack and half from the operator's memory.
Value: !Ref CpuArchitecture
Region:
Description: Region the stack was deployed to.
Value: !Ref AWS::Region
StackTag:
Description: The kirocrew:fargate discovery tag value.
Value: !Ref StackTag
Loading
Loading