@fjall/components-infrastructure 0.89.4 → 0.89.6

package/dist/lib/resources/aws/compute/ecsServiceFactory.js

@@ -0,0 +1,183 @@
+import { FargateService, Ec2Service, PropagatedTagSource, PlacementStrategy, AsgCapacityProvider, EcsOptimizedImage, AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+import { InstanceType, Peer, Port, SubnetType } from "aws-cdk-lib/aws-ec2";
+import { CfnOutput, Duration } from "aws-cdk-lib";
+import { PredefinedMetric, ScalableTarget, ServiceNamespace, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { AutoScalingGroup, Monitoring } from "aws-cdk-lib/aws-autoscaling";
+import { SecurityGroup } from "../networking/securityGroup.js";
+import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
+import { toPascalCase } from "../../../utils/capitaliseString.js";
+import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, inferAmiHardwareType } from "./ecsConstants.js";
+import { ScalingType } from "./ecsTypes.js";
+import { isServiceFargate, isServiceEc2 } from "./ecsTaskDefinition.js";
+/**
+ * Generates a unique key for EC2 config so services with matching
+ * configurations share an ASG.
+ */
+export function getEc2ConfigKey(ec2Config) {
+    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
+    const amiHardwareType = ec2Config.amiHardwareType ??
+        (inferAmiHardwareType(instanceType) === AmiHardwareType.ARM
+            ? "ARM"
+            : "STANDARD");
+    const warmPoolKey = ec2Config.warmPool
+        ? `wp${ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE}-${ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN}`
+        : "nowp";
+    return `${instanceType}-${amiHardwareType}-${warmPoolKey}`;
+}
+/**
+ * Gets or creates an ASG capacity provider for an EC2-backed service.
+ * Services with matching EC2 configs share the same ASG.
+ *
+ * Mutates `state` to track the provider and first ASG/security group.
+ */
+export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
+    const ec2Config = serviceProps.ec2Config ?? {};
+    const key = getEc2ConfigKey(ec2Config);
+    const existing = state.providers.get(key);
+    if (existing) {
+        return existing;
+    }
+    const safeKey = key.replace(/[^a-zA-Z0-9]/g, "");
+    const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
+    const amiHardwareType = ec2Config.amiHardwareType
+        ? ec2Config.amiHardwareType === "STANDARD"
+            ? AmiHardwareType.STANDARD
+            : AmiHardwareType.ARM
+        : inferAmiHardwareType(instanceType);
+    const minCapacity = ec2Config.minCapacity ?? 2;
+    const maxCapacity = ec2Config.maxCapacity ?? 3;
+    const asgSecurityGroup = new SecurityGroup(ctx.scope, `${safeKey}AsgSecurityGroup`, {
+        vpc: ctx.cluster.vpc,
+        description: `Security group for ${key} auto scaling group`
+    });
+    if (ctx.directAccessEnabled) {
+        for (const service of ctx.props.services) {
+            if (isServiceEc2(service)) {
+                for (const container of service.containers) {
+                    if (container.port) {
+                        asgSecurityGroup.addIngressRule(Peer.anyIpv4(), Port.tcp(container.port), `Direct access to container port ${container.port}`);
+                    }
+                }
+            }
+        }
+    }
+    const hasNat = vpcHasNatGateways(ctx.cluster.vpc);
+    const asg = new AutoScalingGroup(ctx.scope, `${safeKey}AutoScalingGroup`, {
+        autoScalingGroupName: `${ctx.props.clusterName}-${safeKey}-Asg`,
+        vpc: ctx.cluster.vpc,
+        vpcSubnets: {
+            subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC
+        },
+        securityGroup: asgSecurityGroup,
+        minCapacity,
+        maxCapacity,
+        instanceType: new InstanceType(instanceType),
+        capacityRebalance: true,
+        instanceMonitoring: Monitoring.BASIC,
+        machineImage: EcsOptimizedImage.amazonLinux2023(amiHardwareType)
+    });
+    if (ec2Config.warmPool) {
+        asg.addWarmPool({
+            minSize: ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE,
+            reuseOnScaleIn: ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN
+        });
+    }
+    const provider = new AsgCapacityProvider(ctx.scope, `${safeKey}AsgCapacityProvider`, {
+        autoScalingGroup: asg,
+        enableManagedDraining: true,
+        enableManagedTerminationProtection: false
+    });
+    ctx.cluster.addAsgCapacityProvider(provider);
+    state.providers.set(key, provider);
+    if (!state.autoScalingGroup) {
+        state.autoScalingGroup = asg;
+    }
+    if (!state.asgSecurityGroup) {
+        state.asgSecurityGroup = asgSecurityGroup;
+    }
+    return provider;
+}
+/**
+ * Creates a Fargate or EC2 service and emits a CfnOutput for its ARN.
+ */
+export function createService(ctx, serviceName, serviceProps, taskDefinition, asgState) {
+    const desiredCount = serviceProps.desiredCount ?? 2;
+    let service;
+    if (isServiceFargate(serviceProps)) {
+        const hasNat = vpcHasNatGateways(ctx.cluster.vpc);
+        service = new FargateService(ctx.scope, `${serviceName}Service`, {
+            cluster: ctx.cluster,
+            taskDefinition: taskDefinition,
+            desiredCount,
+            serviceName,
+            vpcSubnets: {
+                subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC
+            },
+            assignPublicIp: !hasNat,
+            capacityProviderStrategies: [
+                {
+                    capacityProvider: serviceProps.capacityProvider,
+                    weight: 1
+                }
+            ],
+            propagateTags: PropagatedTagSource.SERVICE,
+            circuitBreaker: { enable: true, rollback: true },
+            enableECSManagedTags: true,
+            enableExecuteCommand: true,
+            healthCheckGracePeriod: Duration.seconds(120),
+            minHealthyPercent: 100,
+            maxHealthyPercent: 200
+        });
+    }
+    else {
+        const asgProvider = getOrCreateAsgCapacityProvider(ctx, serviceProps, asgState);
+        service = new Ec2Service(ctx.scope, `${serviceName}Service`, {
+            cluster: ctx.cluster,
+            taskDefinition: taskDefinition,
+            desiredCount,
+            serviceName,
+            capacityProviderStrategies: [
+                {
+                    capacityProvider: asgProvider.capacityProviderName,
+                    weight: 1
+                }
+            ],
+            propagateTags: PropagatedTagSource.SERVICE,
+            circuitBreaker: { enable: true, rollback: true },
+            placementStrategies: [PlacementStrategy.spreadAcrossInstances()],
+            enableECSManagedTags: true,
+            enableExecuteCommand: true,
+            healthCheckGracePeriod: Duration.seconds(120),
+            minHealthyPercent: 100,
+            maxHealthyPercent: 200
+        });
+    }
+    new CfnOutput(ctx.scope, `${ctx.outputName}${toPascalCase(serviceName)}ServiceArn`, {
+        key: `${ctx.outputName}${toPascalCase(serviceName)}ServiceArn`,
+        exportName: `${ctx.props.clusterName}${serviceName}ServiceArn`,
+        value: service.serviceArn,
+        description: `ECS Service ARN for ${serviceName}`
+    });
+    return service;
+}
+/**
+ * Adds auto-scaling to an ECS service based on CPU or memory utilisation.
+ */
+export function addServiceScaling(ctx, serviceName, serviceProps, service) {
+    const scalableTarget = new ScalableTarget(ctx.scope, `${serviceName}ScalableTarget`, {
+        serviceNamespace: ServiceNamespace.ECS,
+        resourceId: `service/${ctx.cluster.clusterName}/${service.serviceName}`,
+        scalableDimension: "ecs:service:DesiredCount",
+        minCapacity: serviceProps.minCapacity ?? 2,
+        maxCapacity: serviceProps.maxCapacity ?? 10
+    });
+    return new TargetTrackingScalingPolicy(ctx.scope, `${serviceName}ScalingPolicy`, {
+        scalingTarget: scalableTarget,
+        predefinedMetric: serviceProps.scalingType === ScalingType.MEMORY
+            ? PredefinedMetric.ECS_SERVICE_AVERAGE_MEMORY_UTILIZATION
+            : PredefinedMetric.ECS_SERVICE_AVERAGE_CPU_UTILIZATION,
+        targetValue: 50,
+        scaleInCooldown: Duration.seconds(60),
+        scaleOutCooldown: Duration.seconds(60)
+    });
+}

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

@@ -0,0 +1,30 @@
+import { FargateTaskDefinition, Ec2TaskDefinition, type ContainerDefinition } from "aws-cdk-lib/aws-ecs";
+import { type Role } from "aws-cdk-lib/aws-iam";
+import type { EcsConstructContext } from "./ecsContext.js";
+import type { EcsClusterProps, EcsServiceProps, EcsCapacityProvider } from "./ecsTypes.js";
+export { createExecutionRole, createTaskRole } from "./ecsRoles.js";
+export { getContainerImage } from "./ecsImages.js";
+/**
+ * Gets the capacity provider for a service.
+ * Each service MUST specify its own capacityProvider.
+ */
+export declare function getServiceCapacityProvider(serviceProps: EcsServiceProps): EcsCapacityProvider;
+/** Checks if a service uses a Fargate capacity provider. */
+export declare function isServiceFargate(serviceProps: EcsServiceProps): boolean;
+/** Checks if a service uses an EC2 capacity provider. */
+export declare function isServiceEc2(serviceProps: EcsServiceProps): boolean;
+/**
+ * Collects Secrets Manager secret names from secretsImport for a specific service.
+ * Scoped per service to enforce least-privilege on execution roles.
+ */
+export declare function collectSecretsManagerSecretNames(props: EcsClusterProps, serviceName: string): string[];
+/**
+ * Derives the SSM secrets path for a service.
+ * Uses explicit path if provided, otherwise derives from app/cluster/service names.
+ */
+export declare function deriveSsmSecretsPath(props: EcsClusterProps, serviceName: string, explicitPath?: string): string;
+export declare function createTaskDefinition(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, executionRole: Role, taskRole: Role): FargateTaskDefinition | Ec2TaskDefinition;
+export declare function addContainersToTask(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, taskDefinition: FargateTaskDefinition | Ec2TaskDefinition): {
+    containers: ContainerDefinition[];
+    primaryContainer?: ContainerDefinition;
+};

package/dist/lib/resources/aws/compute/ecsTaskDefinition.js

@@ -0,0 +1,168 @@
+import { AwsLogDriver, FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, CpuArchitecture, OperatingSystemFamily } from "aws-cdk-lib/aws-ecs";
+import { Duration } from "aws-cdk-lib";
+import { Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
+import { Secret } from "aws-cdk-lib/aws-secretsmanager";
+import { StringParameter } from "aws-cdk-lib/aws-ssm";
+import { validateSsmPathComponent } from "./ecsValidation.js";
+import { DEFAULT_LOG_RETENTION_DAYS } from "./ecsConstants.js";
+import { getContainerImage } from "./ecsImages.js";
+// Re-export extracted functions so existing consumers are not broken
+export { createExecutionRole, createTaskRole } from "./ecsRoles.js";
+export { getContainerImage } from "./ecsImages.js";
+/**
+ * Gets the capacity provider for a service.
+ * Each service MUST specify its own capacityProvider.
+ */
+export function getServiceCapacityProvider(serviceProps) {
+    return serviceProps.capacityProvider;
+}
+/** Checks if a service uses a Fargate capacity provider. */
+export function isServiceFargate(serviceProps) {
+    const provider = getServiceCapacityProvider(serviceProps);
+    return provider === "FARGATE" || provider === "FARGATE_SPOT";
+}
+/** Checks if a service uses an EC2 capacity provider. */
+export function isServiceEc2(serviceProps) {
+    return getServiceCapacityProvider(serviceProps) === "EC2";
+}
+/**
+ * Collects Secrets Manager secret names from secretsImport for a specific service.
+ * Scoped per service to enforce least-privilege on execution roles.
+ */
+export function collectSecretsManagerSecretNames(props, serviceName) {
+    const service = props.services.find((s) => s.name === serviceName);
+    if (!service)
+        return [];
+    const secretNames = new Set();
+    for (const container of service.containers) {
+        if (container.secretsImport) {
+            for (const secretImport of Object.values(container.secretsImport)) {
+                secretNames.add(secretImport.name);
+            }
+        }
+    }
+    return Array.from(secretNames);
+}
+/**
+ * Derives the SSM secrets path for a service.
+ * Uses explicit path if provided, otherwise derives from app/cluster/service names.
+ */
+export function deriveSsmSecretsPath(props, serviceName, explicitPath) {
+    if (explicitPath) {
+        return explicitPath;
+    }
+    const appName = props.appName;
+    if (!appName) {
+        throw new Error(`Service '${serviceName}' has secrets defined but no ssmSecretsPath is set ` +
+            `and appName is not configured on the cluster. ` +
+            `Either set ssmSecretsPath on the service, or set appName on the cluster props ` +
+            `to enable automatic path derivation (/<appName>/<clusterName>/<serviceName>).`);
+    }
+    validateSsmPathComponent(appName, "appName");
+    validateSsmPathComponent(props.clusterName, "clusterName");
+    validateSsmPathComponent(serviceName, "serviceName");
+    return `/${appName}/${props.clusterName}/${serviceName}`;
+}
+export function createTaskDefinition(ctx, serviceName, serviceProps, executionRole, taskRole) {
+    const cpu = serviceProps.cpu ?? 256;
+    const memoryLimitMiB = serviceProps.memoryLimitMiB ?? 512;
+    if (isServiceFargate(serviceProps)) {
+        return new FargateTaskDefinition(ctx.scope, `${serviceName}TaskDefinition`, {
+            family: `${ctx.props.clusterName}-${serviceName}`,
+            cpu,
+            memoryLimitMiB,
+            executionRole,
+            taskRole,
+            runtimePlatform: {
+                cpuArchitecture: CpuArchitecture.ARM64,
+                operatingSystemFamily: OperatingSystemFamily.LINUX
+            }
+        });
+    }
+    else {
+        return new Ec2TaskDefinition(ctx.scope, `${serviceName}TaskDefinition`, {
+            family: `${ctx.props.clusterName}-${serviceName}`,
+            executionRole,
+            taskRole,
+            ...(ctx.directAccessEnabled && { networkMode: NetworkMode.HOST })
+        });
+    }
+}
+export function addContainersToTask(ctx, serviceName, serviceProps, taskDefinition) {
+    const containers = [];
+    let primaryContainer;
+    for (const containerConfig of serviceProps.containers) {
+        const image = getContainerImage(ctx, serviceName, containerConfig, serviceProps);
+        const isFirstWithPort = !primaryContainer && containerConfig.port !== undefined;
+        const secrets = {};
+        if (containerConfig.secretsImport) {
+            for (const [key, secretImport] of Object.entries(containerConfig.secretsImport)) {
+                const secret = Secret.fromSecretNameV2(ctx.scope, `${ctx.props.clusterName}${serviceName}${containerConfig.name}${key}Secret`, secretImport.name);
+                secrets[key] = EcsSecret.fromSecretsManager(secret, secretImport.field);
+            }
+        }
+        if (containerConfig.secrets && containerConfig.secrets.length > 0) {
+            if (containerConfig.secretsImport) {
+                const secretsImportKeys = Object.keys(containerConfig.secretsImport);
+                const duplicateKeys = containerConfig.secrets.filter((key) => secretsImportKeys.includes(key));
+                if (duplicateKeys.length > 0) {
+                    throw new Error(`Container '${containerConfig.name}' in service '${serviceName}' has duplicate secret keys ` +
+                        `defined in both secrets and secretsImport: ${duplicateKeys.join(", ")}. ` +
+                        `Each secret key must be unique across both sources.`);
+                }
+            }
+            const ssmSecretsPath = deriveSsmSecretsPath(ctx.props, serviceName, serviceProps.ssmSecretsPath);
+            for (const secretName of containerConfig.secrets) {
+                const paramPath = `${ssmSecretsPath}/${secretName}`;
+                const param = StringParameter.fromSecureStringParameterAttributes(ctx.scope, `${ctx.props.clusterName}${serviceName}${containerConfig.name}${secretName}SsmParam`, { parameterName: paramPath });
+                secrets[secretName] = EcsSecret.fromSsmParameter(param);
+            }
+        }
+        const container = taskDefinition.addContainer(`${serviceName}${containerConfig.name}`, {
+            image,
+            containerName: containerConfig.name,
+            logging: new AwsLogDriver({
+                streamPrefix: `/ecs/${ctx.props.clusterName}/${serviceName}`,
+                logRetention: DEFAULT_LOG_RETENTION_DAYS
+            }),
+            environment: {
+                ...containerConfig.environment,
+                ...(containerConfig.port
+                    ? { PORT: String(containerConfig.port) }
+                    : {})
+            },
+            secrets,
+            command: containerConfig.command,
+            entryPoint: containerConfig.entryPoint,
+            essential: containerConfig.essential ?? true,
+            healthCheck: containerConfig.healthCheck
+                ? {
+                    command: containerConfig.healthCheck.command,
+                    interval: containerConfig.healthCheck.interval
+                        ? Duration.seconds(containerConfig.healthCheck.interval)
+                        : undefined,
+                    timeout: containerConfig.healthCheck.timeout
+                        ? Duration.seconds(containerConfig.healthCheck.timeout)
+                        : undefined,
+                    retries: containerConfig.healthCheck.retries,
+                    startPeriod: containerConfig.healthCheck.startPeriod
+                        ? Duration.seconds(containerConfig.healthCheck.startPeriod)
+                        : undefined
+                }
+                : undefined,
+            ...(isServiceEc2(serviceProps) && {
+                memoryLimitMiB: serviceProps.ec2Config?.memoryLimitMiB ?? 1024
+            })
+        });
+        if (containerConfig.port) {
+            container.addPortMappings({
+                containerPort: containerConfig.port
+            });
+        }
+        if (isFirstWithPort) {
+            primaryContainer = container;
+        }
+        containers.push(container);
+    }
+    return { containers, primaryContainer };
+}