@raindancers/raindancers-crew 0.0.1 → 0.0.2

package/lib/ecs-crew-host.d.ts

@@ -0,0 +1,247 @@
+import * as autoscaling from 'aws-cdk-lib/aws-autoscaling';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as ecs from 'aws-cdk-lib/aws-ecs';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { Construct } from 'constructs';
+import { FargateCrew } from './fargate-crew';
+import { FargateCrewBase } from './fargate-crew-base';
+import { CrewArchitecture, ICrewBackupBucket } from './remote-crew-instance-props';
+/**
+ * How a per-crew durable EBS volume is exposed to the host and its container.
+ *
+ * The device name the construct asks for (for example `/dev/sdf`) is NOT the
+ * kernel device name on Nitro/Graviton, where every EBS volume surfaces as an
+ * unpredictable `/dev/nvmeXn1`. The bootstrap therefore resolves each volume by
+ * a stable filesystem LABEL, never by the device path.
+ */
+export interface CrewDataVolume {
+    /** The crew this volume belongs to. */
+    readonly crew: string;
+    /** The block device name requested at attach time (a hint, not the kernel name). */
+    readonly deviceName: string;
+    /** The stable filesystem label the bootstrap resolves and mounts by. */
+    readonly label: string;
+    /** The host mount path the container bind-mounts for `~/.kiro/crew`. */
+    readonly mountPath: string;
+}
+/**
+ * Properties for {@link EcsCrewHost}.
+ */
+export interface EcsCrewHostProps {
+    /**
+     * VPC to run in. Passed in, never created here.
+     *
+     * The construct consumes a two-subnet host-NAT topology it does not build:
+     * one PUBLIC subnet (host ENI + Elastic IP + IGW route) and one PRIVATE
+     * subnet (task ENIs, `0.0.0.0/0` -> the host ENI, no IGW route). Select them
+     * with {@link hostSubnets} and {@link taskSubnets}.
+     */
+    readonly vpc: ec2.IVpc;
+    /**
+     * ARN of an IAM permissions boundary applied to the host instance role.
+     *
+     * The host runs a prompt-injectable agent per crew, so its role MUST carry a
+     * boundary that caps blast radius. Required, not optional, matching
+     * {@link RemoteCrewInstanceProps.permissionsBoundaryArn}. Any valid managed-
+     * policy ARN is accepted here (this is the EC2/host boundary).
+     *
+     * The per-crew task/execution roles take {@link crewPermissionsBoundaryArn},
+     * which is validated separately against the `kirocrew-crew-boundary` pattern
+     * the crew roles require.
+     */
+    readonly permissionsBoundaryArn: string;
+    /**
+     * ARN of the pre-created shared crew permissions boundary
+     * (`arn:aws:iam::<account>:policy/kirocrew-crew-boundary`), applied to every
+     * per-crew task and execution role.
+     *
+     * Separate from {@link permissionsBoundaryArn} because the crew roles enforce
+     * the `kirocrew-crew-boundary` policy name (a different boundary from the
+     * host's), and validating them together would force one ARN to satisfy two
+     * distinct patterns. Optional, mirroring {@link FargateCrew}'s declared
+     * degraded mode: omit it only when no crew-boundary creator exists yet.
+     *
+     * @default - no crew boundary (declared degraded mode; see FargateCrew)
+     */
+    readonly crewPermissionsBoundaryArn?: string;
+    /**
+     * EC2 instance type for the single ECS-registered host.
+     *
+     * The type STAYS a settable prop: the 55minutes consumer passes
+     * `new ec2.InstanceType('m9g.xlarge')`. Never hardcoded to one family.
+     *
+     * @default - m7g.2xlarge (arm64) / m7i.2xlarge (x86_64), matching
+     * RemoteCrewInstance
+     */
+    readonly instanceType?: ec2.InstanceType;
+    /**
+     * CPU architecture of the host and the crew container images. Must match
+     * {@link instanceType} when that is set.
+     *
+     * @default CrewArchitecture.ARM64
+     */
+    readonly architecture?: CrewArchitecture;
+    /**
+     * Number of Kiro Crew instances to host, each one ECS task/service.
+     *
+     * DEFAULT 1 — identical to today's single-crew behaviour, so existing
+     * consumers gain nothing new. The 55minutes consumer passes 3. Validated
+     * 1..8: awsvpc gives each task its own ENI, and (crewCount + 1) ENIs (the
+     * host ENI plus one per task) must fit the instance type's ENI budget.
+     *
+     * @default 1
+     */
+    readonly crewCount?: number;
+    /**
+     * Explicit crew names. Each must match the {@link FargateCrew} regex
+     * `^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$`; the log group, roles, and secret
+     * namespace are derived from it. When omitted, names are generated as
+     * `crew-1`..`crew-<crewCount>`. When set, the list length must equal
+     * {@link crewCount}.
+     *
+     * @default - crew-1 .. crew-<crewCount>
+     */
+    readonly crews?: string[];
+    /**
+     * Subnet selection for the host ENI. This is the PUBLIC subnet (IGW-routed,
+     * carries the Elastic IP), because the host does the NAT for the tasks.
+     *
+     * @default - one public subnet in the VPC
+     */
+    readonly hostSubnets?: ec2.SubnetSelection;
+    /**
+     * Subnet selection for the crew task ENIs. This is the PRIVATE subnet whose
+     * `0.0.0.0/0` route points at the host ENI (no IGW route). Tasks get no
+     * public IP.
+     *
+     * @default - the VPC's private-with-egress subnets
+     */
+    readonly taskSubnets?: ec2.SubnetSelection;
+    /**
+     * gp3 root volume size in GiB for the host. Always encrypted.
+     *
+     * @default 60
+     */
+    readonly rootVolumeSizeGb?: number;
+    /**
+     * Per-crew durable EBS data volume size in GiB. Always encrypted, always
+     * `deleteOnTermination: false` (a crew's `~/.kiro/crew` learnings must
+     * outlive an instance replacement, matching the CrewBackupBucket RETAIN
+     * intent).
+     *
+     * @default 20
+     */
+    readonly crewDataVolumeSizeGb?: number;
+    /**
+     * Per-crew EBS volume type.
+     *
+     * @default ec2.EbsDeviceVolumeType.GP3
+     */
+    readonly crewDataVolumeType?: ec2.EbsDeviceVolumeType;
+    /**
+     * SOFT memory reservation (MiB) per crew container. ECS uses it for
+     * placement; a crew may burst above it when the host has spare RAM, so idle
+     * crews cost little.
+     *
+     * @default 1024
+     */
+    readonly crewMemoryReservationMiB?: number;
+    /**
+     * HARD memory cap (MiB) per crew container. A crew is OOM-killed at this
+     * ceiling, so no single crew can consume the whole host. Set the SUM of hard
+     * caps at or below (physical RAM minus host + ECS-agent headroom) for a hard
+     * cross-crew guarantee — see the host-OOM caution in the README.
+     *
+     * @default 2048
+     */
+    readonly crewMemoryHardLimitMiB?: number;
+    /**
+     * Optional SOFT CPU shares per crew container (1024 = one vCPU). Omit to
+     * leave CPU unconstrained (crews share the host CPU fairly under contention).
+     *
+     * @default - unset (shared CPU)
+     */
+    readonly crewCpuShares?: number;
+    /**
+     * ARN of the private ECR repository holding the crew image. Leave unset when
+     * the image is pulled from a public registry. When set, each per-crew
+     * execution role gets a pull grant scoped to this one repository.
+     *
+     * @default - public registry; no pull grant
+     */
+    readonly ecrRepositoryArn?: string;
+    /**
+     * Container image reference for the crew task. When {@link ecrRepositoryArn}
+     * is set this is typically the repo URI with a tag; otherwise a public
+     * registry reference.
+     *
+     * @default 'public.ecr.aws/kirocrew/crew:latest'
+     */
+    readonly crewImage?: string;
+    /**
+     * Days a crew's task logs are kept. One of the CloudWatch retention values
+     * (see {@link FargateCrew}).
+     *
+     * @default 30
+     */
+    readonly logRetentionDays?: number;
+    /**
+     * An S3 backup bucket. When set, each per-crew TASK role is granted write so
+     * the running container pushes its own snapshots off-box.
+     *
+     * @default - no off-box backup
+     */
+    readonly backupBucket?: ICrewBackupBucket;
+    /**
+     * Discovery tag value written as `kirocrew:ecs-host`. Must match
+     * `[a-zA-Z0-9-]{1,51}`. The cluster is named `kirocrew-crew-<stackTag>`.
+     *
+     * @default 'kirocrew'
+     */
+    readonly stackTag?: string;
+}
+/**
+ * One self-provisioned EC2 host running the ECS agent, hosting `crewCount`
+ * Kiro Crew instances as ECS-on-EC2 container tasks.
+ *
+ * The host registers to the {@link FargateCrewBase} cluster and does the NAT
+ * for the crew tasks itself, so the tasks stay fully private with no public
+ * IPs and no NAT Gateway, fck-nat, VPC endpoints, or ALB. Each task runs in
+ * awsvpc mode with its own ENI and private VPC IP; each crew keeps its durable
+ * `~/.kiro/crew` state on its own encrypted EBS volume that survives instance
+ * replacement.
+ *
+ * Isolation is container-level (shared kernel), accepted as sufficient:
+ * Graviton Nitro protects the box from other AWS tenants, containers cover
+ * crew-to-crew separation. See the host-OOM caution: hard per-task memory caps
+ * bound each crew's ceiling but a busy crew can still pressure siblings when
+ * the sum of actual usage exceeds physical RAM.
+ *
+ * `crewCount` defaults to 1, identical to the single-crew shape, so a plain
+ * instantiation with no new props gains no extra resources.
+ */
+export declare class EcsCrewHost extends Construct {
+    /** The shared ECS scaffolding (cluster + egress-only task SG). */
+    readonly base: FargateCrewBase;
+    /** The size-1 Auto Scaling Group holding the single ECS-registered EC2 host. */
+    readonly autoScalingGroup: autoscaling.AutoScalingGroup;
+    /** The capacity provider registering the host with the cluster. */
+    readonly capacityProvider: ecs.AsgCapacityProvider;
+    /** The host instance's IAM role (carries the permissions boundary). */
+    readonly role: iam.Role;
+    /** The host's SSM-only security group (no inbound). */
+    readonly hostSecurityGroup: ec2.SecurityGroup;
+    /** The per-crew scaffolding (roles + log group), one per crew. */
+    readonly crews: FargateCrew[];
+    /** The per-crew EC2 services. */
+    readonly services: ecs.Ec2Service[];
+    /** The per-crew durable data volumes (device/label/mount metadata). */
+    readonly dataVolumes: CrewDataVolume[];
+    /** The discovery tag value written as `kirocrew:ecs-host`. */
+    readonly stackTag: string;
+    /** The resolved crew names. */
+    readonly crewNames: string[];
+    constructor(scope: Construct, id: string, props: EcsCrewHostProps);
+    /** The region the host runs in (read from the stack env, never a prop). */
+    get region(): string;
+}