dcl-ops-lib 9.6.0 → 9.8.0

package/createFargateTask.d.ts

@@ -12,11 +12,11 @@ export type ALBMapping = {
     healthCheck?: Partial<aws.types.input.alb.TargetGroupHealthCheck>;
     extraExposedServiceOptions?: ExtraExposedServiceOptions;
 };
-export declare function getFargateExecutionRole(name: string, policyArnNamedMap: Record<string, pulumi.Input<string> | aws.iam.Policy>): {
+export declare function getFargateExecutionRole(name: string, policyArnNamedMap: Record<string, pulumi.Input<string> | aws.iam.Policy>, existingRole?: aws.iam.Role): {
     role: import("@pulumi/aws/iam/role").Role;
     policies: import("@pulumi/aws/iam/rolePolicyAttachment").RolePolicyAttachment[];
 };
-export declare function getFargateTaskRole(name: string, policyArnNamedMap: Record<string, pulumi.Input<string> | aws.iam.Policy>): {
+export declare function getFargateTaskRole(name: string, policyArnNamedMap: Record<string, pulumi.Input<string> | aws.iam.Policy>, existingRole?: aws.iam.Role): {
     role: import("@pulumi/aws/iam/role").Role;
     policies: import("@pulumi/aws/iam/rolePolicyAttachment").RolePolicyAttachment[];
 };
@@ -43,6 +43,21 @@ export type FargateTaskOptions = {
     nlbMappings?: NLBMapping[];
     executionRolePolicies?: Record<string, pulumi.Input<string> | aws.iam.Policy>;
     taskRolePolicies?: Record<string, pulumi.Input<string> | aws.iam.Policy>;
+    /**
+     * Optional pre-built IAM role to use as the Fargate task role. When provided,
+     * the role is used as-is and `taskRolePolicies` are attached to it. When omitted
+     * (default), a new role is created internally — current behavior, fully backward
+     * compatible. Use this when callers need the task role ARN to exist before the
+     * Fargate task (e.g., to scope a KMS key policy to that exact ARN).
+     */
+    taskRole?: aws.iam.Role;
+    /**
+     * Optional pre-built IAM role to use as the Fargate execution role. When provided,
+     * the role is used as-is and `executionRolePolicies` are attached to it. When
+     * omitted (default), a new role is created internally — current behavior, fully
+     * backward compatible. Symmetric to `taskRole`; same use case.
+     */
+    executionRole?: aws.iam.Role;
     secrets?: aws.ecs.Secret[];
     ignoreServiceDiscovery?: boolean;
     team: Team;
@@ -61,14 +76,7 @@ export type FargateTaskOptions = {
     appAutoscaling?: {
         maxCapacity: number;
         minCapacity?: number;
-        policy?: {
-            metricName: string;
-            targetValue: number;
-            metricDimensionValue: pulumi.Output<string>;
-            statistic: "Average" | "Minimum" | "Maximum";
-            scaleOutCooldown: number;
-            scaleInCooldown: number;
-        }[];
+        policy?: AppAutoscalingPolicy[];
         scheduleAction?: {
             minCapacity: number;
             maxCapacity: number;
@@ -84,6 +92,41 @@ export type FargateTaskOptions = {
     };
     enableExecuteCommand?: boolean;
 };
+/**
+ * One ECS Service Application-Auto-Scaling target-tracking policy.
+ *
+ * Tracks `metricName` (today only `ApproximateNumberOfMessagesVisible` is
+ * understood as an SQS queue depth — anything else falls through with no
+ * `customizedMetricSpecification` set) against `targetValue`. Required
+ * cooldowns are enforced by AWS.
+ *
+ * Choose ONE of:
+ * - `metricDimensionValue`: a single SQS queue URL. The policy tracks that
+ *   queue's depth directly.
+ * - `metricDimensionValues`: 2+ SQS queue URLs. The policy uses CloudWatch
+ *   metric math to track the SUM of their depths under one signal — useful
+ *   when several queues feed the same worker pool and the desired pod count
+ *   must reflect total pending work, not the max of any one queue. (AWS's
+ *   default with N parallel target-tracking policies is max-of-all, which
+ *   undercounts when multiple queues have load simultaneously.)
+ *
+ * Setting both fields, or neither, throws at apply time.
+ */
+export type AppAutoscalingPolicy = {
+    metricName: string;
+    targetValue: number;
+    /** Single-queue form. Mutually exclusive with `metricDimensionValues`. */
+    metricDimensionValue?: pulumi.Output<string>;
+    /**
+     * Multi-queue (sum) form. Mutually exclusive with `metricDimensionValue`.
+     * Must contain ≥1 entry; with a single entry, prefer `metricDimensionValue`
+     * for clarity.
+     */
+    metricDimensionValues?: pulumi.Output<string>[];
+    statistic: "Average" | "Minimum" | "Maximum";
+    scaleOutCooldown: number;
+    scaleInCooldown: number;
+};
 /**
  *
  * @param serviceName A name for this service. For example, "builder-api"
@@ -137,14 +180,7 @@ export type InternalServiceOptions = {
     appAutoscaling?: {
         maxCapacity: number;
         minCapacity?: number;
-        policy?: {
-            metricName: string;
-            targetValue: number;
-            metricDimensionValue: pulumi.Output<string>;
-            statistic: "Average" | "Minimum" | "Maximum";
-            scaleOutCooldown: number;
-            scaleInCooldown: number;
-        }[];
+        policy?: AppAutoscalingPolicy[];
         scheduleAction?: {
             maxCapacity: number;
             minCapacity: number;

package/createFargateTask.js

@@ -49,12 +49,18 @@ async function getClusterInstance(cluster) {
     return cluster.arn;
 }
 exports.getClusterInstance = getClusterInstance;
-function getFargateExecutionRole(name, policyArnNamedMap) {
-    const assumeRolePolicy = aws.iam.assumeRolePolicyForPrincipal({
-        Service: "ecs-tasks.amazonaws.com",
-    });
-    const dependsOn = Object.values(policyArnNamedMap).filter(($) => $ instanceof pulumi.Resource);
-    const role = new aws.iam.Role(name, { assumeRolePolicy }, { dependsOn });
+function getFargateExecutionRole(name, policyArnNamedMap, existingRole) {
+    let role;
+    if (existingRole) {
+        role = existingRole;
+    }
+    else {
+        const assumeRolePolicy = aws.iam.assumeRolePolicyForPrincipal({
+            Service: "ecs-tasks.amazonaws.com",
+        });
+        const dependsOn = Object.values(policyArnNamedMap).filter(($) => $ instanceof pulumi.Resource);
+        role = new aws.iam.Role(name, { assumeRolePolicy }, { dependsOn });
+    }
     const policies = [];
     // Default execution policy
     policies.push(new aws.iam.RolePolicyAttachment(`${name}-default-execution-policy`, {
@@ -72,12 +78,18 @@ function getFargateExecutionRole(name, policyArnNamedMap) {
     return { role, policies };
 }
 exports.getFargateExecutionRole = getFargateExecutionRole;
-function getFargateTaskRole(name, policyArnNamedMap) {
-    const assumeRolePolicy = aws.iam.assumeRolePolicyForPrincipal({
-        Service: "ecs-tasks.amazonaws.com",
-    });
-    const dependsOn = Object.values(policyArnNamedMap).filter(($) => $ instanceof pulumi.Resource);
-    const role = new aws.iam.Role(name, { assumeRolePolicy }, { dependsOn });
+function getFargateTaskRole(name, policyArnNamedMap, existingRole) {
+    let role;
+    if (existingRole) {
+        role = existingRole;
+    }
+    else {
+        const assumeRolePolicy = aws.iam.assumeRolePolicyForPrincipal({
+            Service: "ecs-tasks.amazonaws.com",
+        });
+        const dependsOn = Object.values(policyArnNamedMap).filter(($) => $ instanceof pulumi.Resource);
+        role = new aws.iam.Role(name, { assumeRolePolicy }, { dependsOn });
+    }
     const policies = [];
     Object.entries(policyArnNamedMap).forEach(([key, policyArn]) => {
         if (policyArn instanceof aws.iam.Policy) {
@@ -104,7 +116,7 @@ exports.getFargateTaskRole = getFargateTaskRole;
  * @param options.appAutoscaling Configuration for autoscaling
  */
 async function createFargateTask(serviceName, dockerImage, dockerListeningPort, environment, hostname, options) {
-    let { healthCheck, healthCheckContainer, essential, dontExpose, securityGroups, cluster, memoryReservation, command, version, ephemeralStorageInGB, desiredCount, cpuReservation, extraPortMappings, extraALBMappings, nlbMappings, executionRolePolicies, taskRolePolicies, ignoreServiceDiscovery, secrets, metrics, forceNewDeployment, dontAssignPublicIp, dependsOn, volumes, deregistrationDelay, mountPoints, repositoryCredentials, team, appAutoscaling, enableExecuteCommand, } = options;
+    let { healthCheck, healthCheckContainer, essential, dontExpose, securityGroups, cluster, memoryReservation, command, version, ephemeralStorageInGB, desiredCount, cpuReservation, extraPortMappings, extraALBMappings, nlbMappings, executionRolePolicies, taskRolePolicies, taskRole: existingTaskRole, executionRole: existingExecutionRole, ignoreServiceDiscovery, secrets, metrics, forceNewDeployment, dontAssignPublicIp, dependsOn, volumes, deregistrationDelay, mountPoints, repositoryCredentials, team, appAutoscaling, enableExecuteCommand, } = options;
     if (undefined === essential) {
         essential = true;
     }
@@ -141,9 +153,9 @@ async function createFargateTask(serviceName, dockerImage, dockerListeningPort,
     if (undefined === secrets) {
         secrets = [];
     }
-    const { role: executionRole, policies: executionPolicies } = getFargateExecutionRole(`${serviceName}-${version}-execution`, executionRolePolicies || {});
+    const { role: executionRole, policies: executionPolicies } = getFargateExecutionRole(`${serviceName}-${version}-execution`, executionRolePolicies || {}, existingExecutionRole);
     dependsOn.push(...executionPolicies);
-    const { role: taskRole, policies } = getFargateTaskRole(`${serviceName}-${version}-task`, taskRolePolicies || {});
+    const { role: taskRole, policies } = getFargateTaskRole(`${serviceName}-${version}-task`, taskRolePolicies || {}, existingTaskRole);
     dependsOn.push(...policies);
     let dockerLabels = {};
     if (metrics && (metrics.port || dockerListeningPort)) {
@@ -418,26 +430,78 @@ function setAutoscaling(service, serviceName, config) {
         scalableDimension: "ecs:service:DesiredCount",
         serviceNamespace: "ecs",
     });
+    // The dcl-ops-lib SQS queue convention is to pass `queue.id` (the queue's
+    // URL, e.g., https://sqs.us-east-1.amazonaws.com/.../my-queue) as the
+    // metric dimension value. CloudWatch wants just the queue NAME ("my-queue")
+    // in the dimension, so we trim everything up to and including the last `/`.
+    const extractQueueName = (queueUrl) => queueUrl.apply((value) => value.split("/").pop());
     if (config.appAutoscaling.policy) {
         config.appAutoscaling.policy.forEach((item, index) => {
-            const CSM_ApproximateNumberOfMessagesVisible = {
-                metricName: item.metricName,
-                namespace: "AWS/SQS",
-                dimensions: [
-                    {
-                        name: "QueueName",
-                        value: item.metricDimensionValue.apply((value) => {
-                            return value.split("/").pop();
-                        }),
-                    },
-                ],
-                statistic: item.statistic,
-                unit: "Count",
-            };
+            // Validate the singular/plural choice. Done per-item so the user sees
+            // the failure on the offending policy entry rather than a vague top-
+            // level error after Pulumi has already started planning resources.
+            const hasSingle = item.metricDimensionValue !== undefined;
+            const hasMulti = item.metricDimensionValues !== undefined &&
+                item.metricDimensionValues.length > 0;
+            if (hasSingle && hasMulti) {
+                throw new Error(`appAutoscaling.policy[${index}] sets both metricDimensionValue and metricDimensionValues; pick one.`);
+            }
+            if (!hasSingle && !hasMulti) {
+                throw new Error(`appAutoscaling.policy[${index}] must set either metricDimensionValue or metricDimensionValues (non-empty).`);
+            }
             let TTS_CustomizedMetricSpecification = undefined;
             if (item.metricName === "ApproximateNumberOfMessagesVisible") {
-                TTS_CustomizedMetricSpecification =
-                    CSM_ApproximateNumberOfMessagesVisible;
+                if (hasMulti) {
+                    // Metric-math form: SUM the queue depths into one signal. Each
+                    // queue contributes a `mN` metric stat with returnData=false, and
+                    // a final `e0` expression `m0 + m1 + ...` is the value the scaling
+                    // target tracks. AWS evaluates the expression at policy time.
+                    const dims = item.metricDimensionValues;
+                    const metricStats = dims.map((queueUrl, i) => ({
+                        id: `m${i}`,
+                        metricStat: {
+                            metric: {
+                                metricName: item.metricName,
+                                namespace: "AWS/SQS",
+                                dimensions: [
+                                    {
+                                        name: "QueueName",
+                                        value: extractQueueName(queueUrl),
+                                    },
+                                ],
+                            },
+                            stat: item.statistic,
+                            unit: "Count",
+                        },
+                        returnData: false,
+                    }));
+                    const expression = dims.map((_, i) => `m${i}`).join(" + ");
+                    TTS_CustomizedMetricSpecification = {
+                        metrics: [
+                            ...metricStats,
+                            {
+                                id: "e0",
+                                expression,
+                                returnData: true,
+                            },
+                        ],
+                    };
+                }
+                else {
+                    // Single-queue form (existing behavior, byte-identical output).
+                    TTS_CustomizedMetricSpecification = {
+                        metricName: item.metricName,
+                        namespace: "AWS/SQS",
+                        dimensions: [
+                            {
+                                name: "QueueName",
+                                value: extractQueueName(item.metricDimensionValue),
+                            },
+                        ],
+                        statistic: item.statistic,
+                        unit: "Count",
+                    };
+                }
             }
             return new aws.appautoscaling.Policy(`ecs-autoscaling-policy-${(0, stack_1.getStackScopedName)(serviceName)}-${index.toString()}`, // distinct policies by id
             {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dcl-ops-lib",
-  "version": "9.6.0",
+  "version": "9.8.0",
   "scripts": {
     "build": "tsc && cp bin/* . && node test.js",
     "test": "tsc -p tsconfig.test.json && ENVIRONMENT=dev node bin-test/rateLimiting.test.js",