@fjall/components-infrastructure 0.89.5 → 0.94.0

package/dist/lib/resources/aws/compute/ecs.d.ts

@@ -1,311 +1,17 @@
-import { Cluster as CdkCluster, FargateService, Ec2Service, type RepositoryImage } from "aws-cdk-lib/aws-ecs";
-import { Connections, type IConnectable, type IVpc } from "aws-cdk-lib/aws-ec2";
+import { Cluster as CdkCluster, type FargateService, type Ec2Service } from "aws-cdk-lib/aws-ecs";
+import { Connections, type IConnectable } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
-import { type StackBuilder } from "../base/awsStack";
-import { type ApplicationListener, ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
-import { type IManagedPolicy, type PolicyDocument } from "aws-cdk-lib/aws-iam";
-import { Certificate } from "aws-cdk-lib/aws-certificatemanager";
-import { type GeoLocation } from "aws-cdk-lib/aws-route53";
-import { Repository } from "aws-cdk-lib/aws-ecr";
-import { HostedZone as FjallHostedZone } from "../networking/hostedZone";
-import { type ConnectionSpec } from "../../../utils/connector.js";
-import { type SecretImport } from "../secrets";
-import type { ManagedDomainExports } from "../../../utils/domainTypes";
-export declare enum Protocol {
-    HTTP = 0,
-    HTTPS = 1
-}
-export declare enum ScalingType {
-    CPU = "ECSServiceAverageCPUUtilization",
-    MEMORY = "ECSServiceAverageMemoryUtilization"
-}
-export type EcsCapacityProvider = "FARGATE" | "FARGATE_SPOT" | "EC2";
-/**
- * EC2 capacity configuration for ECS EC2-backed clusters.
- * Only used when capacityProvider is "EC2".
- */
-export interface Ec2CapacityConfig {
-    /** EC2 instance type. Default: "t4g.micro" */
-    instanceType?: string;
-    /** AMI hardware type. Default: "ARM" (Graviton - better cost/performance) */
-    amiHardwareType?: "ARM" | "STANDARD";
-    /** Minimum number of instances. Default: 1 */
-    minCapacity?: number;
-    /** Maximum number of instances. Default: 3 */
-    maxCapacity?: number;
-    /** Memory limit in MiB for the container. Default: 1024 */
-    memoryLimitMiB?: number;
-    /** Warm pool keeps stopped instances for faster start (10-15s vs 60-90s).
-     *  Mirrors generator WarmPool type (generator/src/schemas/computeSchemas.ts). */
-    warmPool?: {
-        /** Minimum instances to keep in the warm pool. Default: 1 */
-        minSize?: number;
-        /** Return instances to the pool on scale-in instead of terminating. Default: true */
-        reuseOnScaleIn?: boolean;
-    };
-}
-/**
- * Domain configuration for HTTPS and DNS.
- */
-export interface DomainBaseConfig {
-    domainName: string;
-    hostedZone?: FjallHostedZone;
-    certificate?: Certificate;
-    setIdentifier?: string;
-    /** Import zone and cert from a managed domain stack via Fn.importValue() */
-    managedDomain?: ManagedDomainExports;
-}
-export interface LatencyDomainConfig extends DomainBaseConfig {
-    region: string;
-}
-export interface WeightedDomainConfig extends DomainBaseConfig {
-    weight: number;
-}
-export interface GeoLocationDomainConfig extends DomainBaseConfig {
-    geoLocation: GeoLocation;
-}
-export type DomainConfig = DomainBaseConfig | LatencyDomainConfig | WeightedDomainConfig | GeoLocationDomainConfig;
-/**
- * Internal configuration for a container in a multi-container ECS task.
- *
- * In multi-container tasks, the first container with a `port` is the **primary container**
- * that receives load balancer traffic. All other containers are **sidecars** that provide
- * supporting functionality (logging, monitoring, proxies, etc.).
- *
- * @example
- * // Primary container (has port) + sidecar (no port)
- * containers: [
- *   { name: "app", port: 3000 },           // Primary - receives ALB traffic
- *   { name: "datadog", image: "datadog/agent" }  // Sidecar - monitoring
- * ]
- *
- * @internal
- */
-export interface EcsClusterContainerConfig {
-    /** Unique container name */
-    name: string;
-    /**
-     * Container image. Options:
-     * - Omit: Uses default ECR repository (primary container only)
-     * - string: ECR repository name or public image URL
-     * - Repository: CDK ECR Repository construct
-     */
-    image?: string | Repository;
-    /**
-     * Port the container listens on.
-     * The first container with a port becomes the **primary container**
-     * and is registered with the load balancer.
-     */
-    port?: number;
-    /** Environment variables */
-    environment?: Record<string, string>;
-    /**
-     * Secrets from AWS SSM Parameter Store.
-     * Array of secret names that will be fetched from the service's SSM namespace.
-     *
-     * @example
-     * secrets: ["API_KEY", "DB_PASSWORD"]
-     */
-    secrets?: string[];
-    /** Secrets imported from other CDK resources (AWS Secrets Manager) */
-    secretsImport?: {
-        [key: string]: SecretImport;
-    };
-    /** Command to run in the container */
-    command?: string[];
-    /** Entry point for the container */
-    entryPoint?: string[];
-    /**
-     * Whether this container is essential.
-     * If an essential container stops, all containers in the task stop.
-     * Default: true for primary container, true for sidecars
-     */
-    essential?: boolean;
-    /**
-     * Health check configuration.
-     * Default: For primary container with port, uses curl health check.
-     */
-    healthCheck?: {
-        command: string[];
-        interval?: number;
-        timeout?: number;
-        retries?: number;
-        startPeriod?: number;
-    };
-}
-/**
- * Cluster-level configuration.
- * Controls the shared ALB for all services in this cluster.
- */
-export interface EcsClusterClusterConfig {
-    /**
-     * Domain for HTTPS access.
-     * - Omit: ALB created with default DNS (*.elb.amazonaws.com)
-     * - Specified: Creates ACM certificate + Route53 DNS A record
-     */
-    domain?: string;
-    /**
-     * Load balancer configuration.
-     * - false: No ALB (for workers/internal services)
-     * - "public": Internet-facing ALB (default)
-     * - "internal": VPC-only ALB
-     */
-    loadBalancer?: false | "public" | "internal";
-    /**
-     * Enable direct EC2 access without ALB.
-     * Opens container ports on security group for direct access via EC2 public IP.
-     * Uses host network mode for predictable port mapping (container:3000 → host:3000).
-     * Only valid with EC2 capacity provider.
-     */
-    directAccess?: boolean;
-    /**
-     * Domain configuration for advanced routing policies (latency, weighted, geo).
-     * Only used when domain is specified.
-     */
-    domainConfig?: DomainConfig;
-}
-/**
- * Routing configuration for path/host-based routing on the ALB.
- */
-export interface EcsRoutingConfig {
-    /** Path pattern for routing (e.g., "/api/*", "/users/*") */
-    path?: string;
-    /** Host header for routing (e.g., "api.example.com") */
-    host?: string;
-    /** Priority for this routing rule (1-50000). Lower = higher priority. */
-    priority?: number;
-    /** Health check path for this service's target group. Default: "/" */
-    healthCheckPath?: string;
-}
-/**
- * Configuration for a service in an ECS cluster.
- * Each service gets its own task definition, scaling, and target group.
- */
-export interface EcsServiceProps {
-    /** Service name (unique within cluster) */
-    name: string;
-    /**
-     * Container image for this service.
-     * - Omit: Uses cluster's default ECR repository
-     * - string: ECR repository name or public image URL
-     * - Repository: CDK ECR Repository construct
-     */
-    image?: string | Repository;
-    /**
-     * Container configurations for this service.
-     * The first container with a port is the **primary container** (receives ALB traffic).
-     */
-    containers: EcsClusterContainerConfig[];
-    /** CPU units for this service's tasks (256-4096) */
-    cpu?: number;
-    /** Memory in MiB for this service's tasks (512-30720) */
-    memoryLimitMiB?: number;
-    /** Desired number of tasks. Default: 2 */
-    desiredCount?: number;
-    /** Scaling type (CPU or MEMORY). Omit to disable auto-scaling. */
-    scalingType?: ScalingType;
-    /** Minimum number of tasks for auto-scaling. Default: 2 */
-    minCapacity?: number;
-    /** Maximum number of tasks for auto-scaling. Default: 10 */
-    maxCapacity?: number;
-    /**
-     * Routing rules for this service on the cluster's ALB.
-     * Required when cluster has multiple services with ports.
-     * Can be a single rule or an array of rules pointing to the same target group.
-     */
-    routing?: EcsRoutingConfig | EcsRoutingConfig[];
-    /**
-     * Additional inline policies for this service's task role.
-     * Added on top of the default ECS Exec permissions.
-     */
-    taskRoleInlinePolicies?: {
-        [name: string]: PolicyDocument;
-    };
-    /**
-     * Additional managed policies for this service's task role.
-     * Added on top of the default ECS Exec permissions.
-     */
-    taskRoleManagedPolicies?: IManagedPolicy[];
-    /**
-     * Resources this service needs to connect to (e.g., databases, S3 buckets, SQS queues).
-     * Creates security group rules for IConnectable resources and IAM grants for IAM resources.
-     *
-     * Supports:
-     * - IConnectable: Security group resources (RDS, ECS, etc.)
-     * - IStorageConnector: S3 buckets (IAM grants)
-     * - IDynamoDBConnector: DynamoDB tables (IAM grants)
-     * - IQueueConnector: SQS queues (IAM grants)
-     * - ConnectionConfig: Explicit access level configuration
-     *
-     * @example
-     * connections: [
-     *   database,                              // Security group (RDS)
-     *   { resource: cache, access: "read" },   // Read-only DynamoDB
-     *   { resource: bucket, access: "write" }, // Write-only S3
-     *   { resource: queue, access: "consume" } // Consume-only SQS
-     * ]
-     */
-    connections?: ConnectionSpec[];
-    /**
-     * Capacity provider for this service. REQUIRED.
-     * Each service specifies its own capacity provider.
-     */
-    capacityProvider: EcsCapacityProvider;
-    /**
-     * EC2 capacity configuration for this service.
-     * Only used when service capacityProvider is "EC2".
-     * Services with matching ec2Config share an ASG for efficiency.
-     */
-    ec2Config?: Ec2CapacityConfig;
-    /**
-     * SSM Parameter Store path for secrets.
-     * If containers have secrets defined, this path is used as the base path.
-     * Format: /<app>/<cluster>/<service>
-     *
-     * @example
-     * ssmSecretsPath: "/myapp/api-cluster/users"
-     */
-    ssmSecretsPath?: string;
-    /**
-     * Docker build target stage for multi-stage Dockerfiles.
-     * When specified, appends `-<target>` to the image tag.
-     *
-     * @example
-     * // With dockerTarget: "api", image tag becomes: myservice-api-latest
-     * dockerTarget: "api"
-     */
-    dockerTarget?: string;
-}
-/**
- * Props for creating an ECS cluster with multiple services.
- */
-export type EcsClusterProps = {
-    /** Cluster name */
-    clusterName: string;
-    /**
-     * Application name for SSM secrets namespace.
-     * Required when any container uses secrets without explicit ssmSecretsPath.
-     * Used to build the path: /<appName>/<clusterName>/<serviceName>
-     */
-    appName?: string;
-    /** VPC to deploy into */
-    vpc?: IVpc;
-    /** Default ECR repository or container image */
-    ecrRepository: Repository | RepositoryImage | string;
-    /**
-     * Cluster configuration.
-     * Controls the shared ALB for all services.
-     */
-    cluster?: EcsClusterClusterConfig;
-    /**
-     * Services in this cluster.
-     * Each service gets its own task definition, scaling, and target group.
-     * Each service MUST specify its own capacityProvider.
-     * All services share the cluster's ALB (unless disabled).
-     * Task role policies are configured per-service for least-privilege.
-     */
-    services: EcsServiceProps[];
-};
+import type { StackBuilder } from "../base/awsStack.js";
+import type { ApplicationListener, ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type EcsClusterProps } from "./ecsTypes.js";
+export * from "./ecsTypes.js";
+export * from "./ecsConstants.js";
+export * from "./ecsContext.js";
+export * from "./ecsTaskDefinition.js";
+export * from "./ecsNetworking.js";
+export { CapacityProviderDependencyAspect } from "./ecsCapacityProviderAspect.js";
+export { validateEcsClusterProps, validateSsmPathComponent } from "./ecsValidation.js";
+export * from "./ecsServiceFactory.js";
 /**
  * ECS Cluster supporting multiple services with a shared ALB.
  *
@@ -347,23 +53,17 @@ export default class EcsCluster extends Construct implements IConnectable {
     private cluster;
     private loadBalancer?;
     private loadBalancerListener?;
-    private hostedZone?;
     private certificate?;
-    private aRecord?;
-    private autoScalingGroup?;
-    private asgSecurityGroup?;
-    private asgCapacityProvider?;
-    private loadBalancerSecurityGroup?;
+    private asgState;
     private services;
-    private asgCapacityProviders;
     private scope;
     private props;
     private outputName;
     private loadBalancerDisabled;
     private directAccessEnabled;
-    private nextPriority;
-    private usedPriorities;
+    private priorityState;
     constructor(scope: Construct, id: string, props: EcsClusterProps);
+    private get ctx();
     /** Get the cluster's load balancer. Undefined if disabled. */
     getLoadBalancer(): ApplicationLoadBalancer | undefined;
     /** Get the load balancer's listener. Undefined if disabled. */
@@ -381,95 +81,17 @@ export default class EcsCluster extends Construct implements IConnectable {
      * Each service gets its own task definition, containers, and target group.
      */
     private addServiceToCluster;
-    private validateProps;
     private setupConnections;
-    /**
-     * Creates the execution role for ECS infrastructure operations.
-     * Used by the ECS agent to pull images, write logs, and inject secrets.
-     * NOT used by application code - that's the task role.
-     */
-    private createExecutionRole;
-    /**
-     * Creates the task role for application code running in the container.
-     * This role is assumed by the application, not the ECS agent.
-     * Includes default ECS Exec permissions plus any service-specific policies.
-     */
-    private createTaskRole;
-    private createTaskDefinition;
-    private addContainersToTask;
-    private getContainerImage;
-    private createService;
-    private registerServiceWithALB;
-    /** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
-    private getNextPriority;
-    private buildRoutingConditions;
-    private addServiceScaling;
-    /**
-     * Check if the VPC has NAT gateways.
-     * - For Fjall Vpc: uses hasNatGateways property
-     * - For other VPCs: checks if private subnets exist (assumes NAT if present)
-     */
-    private vpcHasNatGateways;
     /**
      * Create DeployableService outputs for deployment automation.
      * Each service gets a DeployableService output so the deployment service
      * can find and deploy all services in the cluster.
      */
     private addDeployableServiceOutputs;
-    /**
-     * Gets the capacity provider for a service.
-     * Each service MUST specify its own capacityProvider.
-     */
-    private getServiceCapacityProvider;
-    /**
-     * Checks if a service uses a Fargate capacity provider.
-     */
-    private isServiceFargate;
-    /**
-     * Checks if a service uses an EC2 capacity provider.
-     */
-    private isServiceEc2;
-    /**
-     * Validates an SSM path component for correctness.
-     * SSM parameter paths have specific constraints that must be enforced.
-     *
-     * @param component - The path component to validate
-     * @param fieldName - Name of the field for error messages
-     * @throws Error if the component is invalid
-     */
-    private validateSsmPathComponent;
-    /**
-     * Collects all Secrets Manager secret names from secretsImport across all services.
-     * Used to scope IAM permissions for least-privilege access.
-     */
-    private collectSecretsManagerSecretNames;
-    /**
-     * Derives the SSM secrets path for a service.
-     * Uses explicit path if provided, otherwise derives from app/cluster/service names.
-     */
-    private deriveSsmSecretsPath;
-    /**
-     * Generates a unique key for EC2 config (for ASG deduplication).
-     * Services with matching keys share an ASG.
-     */
-    private getEc2ConfigKey;
-    /**
-     * Gets or creates an ASG capacity provider for a service.
-     * Services with matching EC2 configs share the same ASG.
-     */
-    private getOrCreateAsgCapacityProvider;
-    /**
-     * Checks if any service in the cluster uses a Fargate capacity provider.
-     */
+    /** Checks if any service in the cluster uses a Fargate capacity provider. */
     private anyServiceUsesFargate;
-    /**
-     * Checks if any service in the cluster uses an EC2 capacity provider.
-     */
+    /** Checks if any service in the cluster uses an EC2 capacity provider. */
     private anyServiceUsesEc2;
     private addCluster;
-    private addLoadBalancer;
-    private addDirectAccessOutputs;
-    private addLoadBalancerListener;
-    private addHostedZone;
     static build(id: string, props: EcsClusterProps): (sb: StackBuilder) => Construct;
 }