@fjall/components-infrastructure 0.77.4 → 0.78.5

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

@@ -1,13 +1,12 @@
-import { ContainerImage, type RepositoryImage } from "aws-cdk-lib/aws-ecs";
+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 { Construct } from "constructs";
 import { type StackBuilder } from "../base/awsStack";
-import { type SecretValue } from "aws-cdk-lib";
+import { type ApplicationListener, ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
 import { type IManagedPolicy, 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 { type KeyValue } from "../../../types";
 import { HostedZone as FjallHostedZone } from "../../../patterns/aws/hostedZone";
 import { type SecretImport } from "../secrets";
 export declare enum Protocol {
@@ -18,14 +17,25 @@ export declare enum ScalingType {
     CPU = "ECSServiceAverageCPUUtilization",
     MEMORY = "ECSServiceAverageMemoryUtilization"
 }
-export interface ContainerSecret {
-    [key: string]: SecretValue;
+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: "t3.micro" */
+    instanceType?: string;
+    /** AMI hardware type. Default: "ARM" (Graviton - better cost/performance) */
+    amiHardwareType?: "ARM" | "STANDARD";
+    /** Minimum number of instances. Default: 2 */
+    minCapacity?: number;
+    /** Maximum number of instances. Default: 3 */
+    maxCapacity?: number;
+    /** Memory limit in MiB for the container. Default: 1024 */
+    memoryLimitMiB?: number;
 }
 /**
- * DomainConfiguration
- * - When supplied a domain name, a hosted zone, certificate and ARecord will be created
- * - When supplied a domain name and hosted zone, a certificate and ARecord will be created
- * - When all properties are supplied only a target will be created
+ * Domain configuration for HTTPS and DNS.
  */
 export interface DomainBaseConfig {
     domainName: string;
@@ -43,67 +53,294 @@ export interface GeoLocationDomainConfig extends DomainBaseConfig {
     geoLocation: GeoLocation;
 }
 export type DomainConfig = DomainBaseConfig | LatencyDomainConfig | WeightedDomainConfig | GeoLocationDomainConfig;
-export type FargateClusterProps = {
-    ecrRepository: Repository | RepositoryImage;
-    clusterName: string;
-    containerCommand?: string[];
-    containerEnvironment?: KeyValue;
-    containerSecrets?: ContainerSecret;
-    containerSecretsImport?: {
+/**
+ * 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 imported from other resources */
+    secretsImport?: {
         [key: string]: SecretImport;
     };
-    containerPort?: number;
-    cpu?: number;
+    /** 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;
-    desiredCount?: number;
+}
+/**
+ * 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;
-    listenerPort?: number;
+}
+/**
+ * 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;
-    publicLoadBalancer?: boolean;
-    protocol: Protocol;
+    /** Desired number of tasks. Default: 2 */
+    desiredCount?: number;
+    /** Scaling type (CPU or MEMORY). Omit to disable auto-scaling. */
     scalingType?: ScalingType;
-    serviceName: string;
+    /** 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.
+     */
+    routing?: 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).
+     * Creates security group rules to allow traffic from this specific service only.
+     */
+    connections?: IConnectable[];
+}
+/**
+ * Props for creating an ECS cluster with multiple services.
+ */
+export type EcsClusterProps = {
+    /** Cluster name */
+    clusterName: string;
+    /** VPC to deploy into */
     vpc?: IVpc;
+    /** Default ECR repository or container image */
+    ecrRepository: Repository | RepositoryImage | string;
+    /** Capacity provider determines Fargate vs EC2 infrastructure */
+    capacityProvider?: EcsCapacityProvider;
+    /** EC2-specific configuration. Only used when capacityProvider is "EC2" */
+    ec2Config?: Ec2CapacityConfig;
+    /**
+     * 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.
+     * All services share the cluster's ALB (unless disabled).
+     * Task role policies are configured per-service for least-privilege.
+     */
+    services: EcsServiceProps[];
 };
-export default class FargateCluster extends Construct implements IConnectable {
+/**
+ * ECS Cluster supporting multiple services with a shared ALB.
+ *
+ * @example
+ * // Single service cluster
+ * new EcsCluster(scope, "WebCluster", {
+ *   clusterName: "WebCluster",
+ *   ecrRepository: ecr,
+ *   services: [
+ *     { name: "web", containers: [{ name: "app", port: 3000 }] }
+ *   ]
+ * });
+ *
+ * @example
+ * // Multi-service cluster with routing
+ * new EcsCluster(scope, "ApiCluster", {
+ *   clusterName: "ApiCluster",
+ *   cluster: { domain: "api.example.com" },
+ *   ecrRepository: ecr,
+ *   services: [
+ *     { name: "users", containers: [{ name: "app", port: 3000 }], routing: { path: "/users/*" } },
+ *     { name: "orders", containers: [{ name: "app", port: 3001 }], routing: { path: "/orders/*" } }
+ *   ]
+ * });
+ *
+ * @example
+ * // Worker cluster (no ALB)
+ * new EcsCluster(scope, "Workers", {
+ *   clusterName: "Workers",
+ *   cluster: { loadBalancer: false },
+ *   ecrRepository: ecr,
+ *   services: [
+ *     { name: "processor", containers: [{ name: "worker" }] }
+ *   ]
+ * });
+ */
+export default class EcsCluster extends Construct implements IConnectable {
     connections: Connections;
     private cluster;
-    private loadBalancer;
-    private executionRole;
-    private taskDefinition;
-    private containerDefinition;
-    private fargateService;
-    private scalingPolicy;
-    private hostedZone;
-    private certificate;
-    private aRecord;
-    private loadBalancerListener;
-    private secrets;
+    private loadBalancer?;
+    private loadBalancerListener?;
+    private hostedZone?;
+    private certificate?;
+    private aRecord?;
+    private autoScalingGroup?;
+    private asgSecurityGroup?;
+    private asgCapacityProvider?;
+    private loadBalancerSecurityGroup?;
+    private drainWaiter?;
+    private fargateCapacityProviderAssociations?;
+    private services;
     private scope;
-    constructor(scope: Construct, id: string, props: FargateClusterProps);
-    addCluster(props: FargateClusterProps): void;
-    /**
-     * #todo: change this to create new secrets instead
-     * @deprecated use importSecrets instead
-     */
-    addSecrets(props: FargateClusterProps): void;
-    /**
-     * Automatically import secrets from another resource or stack
-     */
-    importSecrets(props: FargateClusterProps): void;
-    addExecutionRole(props: FargateClusterProps): void;
-    addTaskDefinition(props: FargateClusterProps): void;
-    addContainerDefinition(props: FargateClusterProps): void;
-    addFargateService(props: FargateClusterProps): void;
-    addScalingPolicy(props: FargateClusterProps): void;
-    registerLoadBalancerTargets(props: FargateClusterProps): void;
-    addLoadBalancer(props: FargateClusterProps): void;
-    addLoadBalancerListener(props: FargateClusterProps): void;
-    addHostedZone(props: FargateClusterProps): void;
-    getImage(props: FargateClusterProps): ContainerImage;
-    static build(id: string, props: FargateClusterProps): (sb: StackBuilder) => Construct;
+    private props;
+    private capacityProvider;
+    private loadBalancerDisabled;
+    private directAccessEnabled;
+    private nextPriority;
+    constructor(scope: Construct, id: string, props: EcsClusterProps);
+    /** Get the cluster's load balancer. Undefined if disabled. */
+    getLoadBalancer(): ApplicationLoadBalancer | undefined;
+    /** Get the load balancer's listener. Undefined if disabled. */
+    getListener(): ApplicationListener | undefined;
+    /** Get a specific service by name. */
+    getService(name: string): FargateService | Ec2Service | undefined;
+    /** Get all services in this cluster. */
+    getServices(): Map<string, FargateService | Ec2Service>;
+    /** Get the ECS cluster construct. */
+    getCluster(): CdkCluster;
+    /** Get the ALB URL (http:// or https://). */
+    getUrl(): string | undefined;
+    /**
+     * Add a service to the cluster.
+     * 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;
+    private buildRoutingConditions;
+    private addServiceScaling;
+    private isEc2;
+    private isFargate;
+    addCluster(props: EcsClusterProps): void;
+    addAutoScalingGroup(props: EcsClusterProps): void;
+    addLoadBalancer(props: EcsClusterProps): void;
+    private addDirectAccessOutputs;
+    addLoadBalancerListener(props: EcsClusterProps): void;
+    addHostedZone(props: EcsClusterProps): void;
+    static build(id: string, props: EcsClusterProps): (sb: StackBuilder) => Construct;
 }