@fjall/components-infrastructure 0.95.0 → 0.99.1

package/dist/lib/patterns/aws/vpcPeerAccepter.js

@@ -0,0 +1,196 @@
+import { Annotations, Stack } from "aws-cdk-lib";
+import { Peer, Port, SubnetType } from "aws-cdk-lib/aws-ec2";
+import { CfnResourcePolicy, StringListParameter, StringParameter } from "aws-cdk-lib/aws-ssm";
+import { CIDR_REGEX, VALIDATION_PATTERNS } from "@fjall/generator";
+import { buildSsmPrefix, DEFAULT_ORG_ID, resolveOrgId } from "../../utils/cdkContext.js";
+import { VpcPeeringAccepterRole } from "../../resources/aws/networking/vpcPeeringAccepterRole.js";
+import { isDatabase, isRelationalDatabase } from "./interfaces/database.js";
+import { isCompute, isEcsCompute } from "./interfaces/compute.js";
+export class VpcPeerAccepterFactory {
+    static build(id, props) {
+        return (app, scope) => {
+            if (props.requesterAccountIds.length === 0) {
+                throw new Error("VpcPeerAccepterFactory requires at least one requester account ID.");
+            }
+            for (const accountId of props.requesterAccountIds) {
+                if (!VALIDATION_PATTERNS.AWS_ACCOUNT_ID.test(accountId)) {
+                    throw new Error(`Invalid requester account ID "${accountId}". Must be a 12-digit AWS account ID.`);
+                }
+            }
+            const localVpc = app.getVpc(props.localVpcName);
+            const accepterRole = new VpcPeeringAccepterRole(scope, id, {
+                requesterAccountIds: props.requesterAccountIds,
+                localVpc,
+                costAllocationEnvironment: props.costAllocationEnvironment,
+                costAllocationDomain: props.costAllocationDomain
+            });
+            const orgId = resolveOrgId(app.node, DEFAULT_ORG_ID);
+            const ssmPrefix = buildSsmPrefix(orgId, app.getName());
+            const publishVpcMetadata = props.publishToSsm ?? true;
+            const vpcMetadataParams = [];
+            if (publishVpcMetadata) {
+                const vpcIdParam = new StringParameter(scope, `${id}VpcIdParam`, {
+                    parameterName: `${ssmPrefix}/vpc-id`,
+                    stringValue: localVpc.vpcId
+                });
+                const vpcCidrParam = new StringParameter(scope, `${id}VpcCidrParam`, {
+                    parameterName: `${ssmPrefix}/vpc-cidr`,
+                    stringValue: localVpc.vpcCidrBlock
+                });
+                const roleArnParam = new StringParameter(scope, `${id}PeeringRoleArnParam`, {
+                    parameterName: `${ssmPrefix}/peering-role-arn`,
+                    stringValue: accepterRole.roleArn
+                });
+                const privateSubnets = localVpc.selectSubnets({
+                    subnetType: SubnetType.PRIVATE_WITH_EGRESS
+                });
+                const routeTableIds = privateSubnets.subnets.map((s) => s.routeTable.routeTableId);
+                const routeTableIdsParam = new StringListParameter(scope, `${id}RouteTableIdsParam`, {
+                    parameterName: `${ssmPrefix}/route-table-ids`,
+                    stringListValue: routeTableIds
+                });
+                vpcMetadataParams.push(vpcIdParam, vpcCidrParam, roleArnParam, routeTableIdsParam);
+            }
+            if (vpcMetadataParams.length > 0) {
+                attachCrossAccountReadPolicy(scope, id, props.requesterAccountIds, vpcMetadataParams);
+            }
+            applyExposedResources(scope, id, ssmPrefix, props.requesterAccountIds, props.exposedResources ?? []);
+            return accepterRole;
+        };
+    }
+}
+function applyExposedResources(accepterScope, id, ssmPrefix, requesterAccountIds, entries) {
+    const seenNames = new Set();
+    for (const entry of entries) {
+        if (seenNames.has(entry.name)) {
+            throw new Error(`Duplicate exposedResource name '${entry.name}' — each exposed resource must have a unique name.`);
+        }
+        seenNames.add(entry.name);
+        for (const cidr of entry.allowedFromCidrs) {
+            if (!CIDR_REGEX.test(cidr)) {
+                throw new Error(`exposedResource '${entry.name}' has malformed CIDR '${cidr}' — expected dotted-quad/prefix-length form (e.g. 10.0.0.0/16).`);
+            }
+        }
+        const resourcePrefix = `${ssmPrefix}/resources/${entry.name}`;
+        const constructPrefix = `${id}Exposed${entry.name}`;
+        const { params, scope: resourceScope } = resolveExposedResource(accepterScope, constructPrefix, resourcePrefix, entry);
+        if (params.length > 0) {
+            attachCrossAccountReadPolicy(resourceScope, constructPrefix, requesterAccountIds, params);
+        }
+    }
+}
+function resolveExposedResource(accepterScope, constructPrefix, resourcePrefix, entry) {
+    if ("serviceName" in entry) {
+        const resource = entry.resource;
+        if (!isCompute(resource) || !isEcsCompute(resource)) {
+            throw new Error(`exposedResource '${entry.name}' carries 'serviceName' (ECS variant) but its resource is not IEcsCompute.`);
+        }
+        const scope = stackOfNode(resource.node);
+        const params = applyEcsServiceExposure(scope, constructPrefix, resourcePrefix, entry);
+        return { params, scope };
+    }
+    const resource = entry.resource;
+    if (!isDatabase(resource) || !isRelationalDatabase(resource)) {
+        throw new Error(`exposedResource '${entry.name}' has no 'serviceName' (database variant) but its resource is not IRelationalDatabase.`);
+    }
+    const scope = stackOfNode(resource.node);
+    const params = applyDatabaseExposure(scope, constructPrefix, resourcePrefix, {
+        ...entry,
+        resource
+    });
+    return { params, scope };
+}
+function applyDatabaseExposure(scope, constructPrefix, resourcePrefix, entry) {
+    const port = parseInt(entry.resource.getHostPort(), 10);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`exposedResource '${entry.name}' resolved an out-of-range port from getHostPort() (must be 1-65535); cannot open ingress.`);
+    }
+    if (entry.allowedFromCidrs.length === 0) {
+        Annotations.of(scope).addWarning(`exposedResource '${entry.name}' has no allowed CIDRs; consumers will not be able to reach it.`);
+        return [];
+    }
+    for (const cidr of entry.allowedFromCidrs) {
+        entry.resource.connections.allowFrom(Peer.ipv4(cidr), Port.tcp(port), `fjall:peer:${cidr}`);
+    }
+    return publishExposedResourceParams(scope, constructPrefix, resourcePrefix, {
+        kind: "relational-db",
+        endpoint: entry.resource.getHostEndpoint(),
+        port: String(port),
+        access: entry.access
+    });
+}
+function applyEcsServiceExposure(scope, constructPrefix, resourcePrefix, entry) {
+    const loadBalancer = entry.resource.getLoadBalancer();
+    if (!loadBalancer) {
+        throw new Error(`exposedResource '${entry.name}' targets ECS service '${entry.serviceName}' but the cluster has no load balancer (cluster.loadBalancer: false). Enable an internal ALB to expose this service.`);
+    }
+    const resolvedListenerPort = entry.port === undefined
+        ? entry.resource.getPrimaryListenerPort()
+        : undefined;
+    const port = entry.port ?? resolvedListenerPort ?? 443;
+    if (entry.port === undefined && resolvedListenerPort !== undefined) {
+        Annotations.of(scope).addInfo(`exposedResource '${entry.name}' defaulted to listener port ${resolvedListenerPort}`);
+    }
+    if (entry.allowedFromCidrs.length === 0) {
+        Annotations.of(scope).addWarning(`exposedResource '${entry.name}' has no allowed CIDRs; consumers will not be able to reach it.`);
+        return [];
+    }
+    for (const cidr of entry.allowedFromCidrs) {
+        loadBalancer.connections.allowFrom(Peer.ipv4(cidr), Port.tcp(port), `fjall:peer:${cidr}`);
+    }
+    return publishExposedResourceParams(scope, constructPrefix, resourcePrefix, {
+        kind: "ecs-service",
+        endpoint: loadBalancer.loadBalancerDnsName,
+        port: String(port)
+    });
+}
+function publishExposedResourceParams(scope, constructPrefix, resourcePrefix, values) {
+    const kindParam = new StringParameter(scope, `${constructPrefix}KindParam`, {
+        parameterName: `${resourcePrefix}/kind`,
+        stringValue: values.kind
+    });
+    const endpointParam = new StringParameter(scope, `${constructPrefix}EndpointParam`, {
+        parameterName: `${resourcePrefix}/endpoint`,
+        stringValue: values.endpoint
+    });
+    const portParam = new StringParameter(scope, `${constructPrefix}PortParam`, {
+        parameterName: `${resourcePrefix}/port`,
+        stringValue: values.port
+    });
+    const params = [kindParam, endpointParam, portParam];
+    if (values.access !== undefined) {
+        const accessParam = new StringParameter(scope, `${constructPrefix}AccessParam`, {
+            parameterName: `${resourcePrefix}/access`,
+            stringValue: values.access
+        });
+        params.push(accessParam);
+    }
+    return params;
+}
+function attachCrossAccountReadPolicy(scope, id, requesterAccountIds, parameters) {
+    const partition = Stack.of(scope).partition;
+    const principals = requesterAccountIds.map((accountId) => `arn:${partition}:iam::${accountId}:root`);
+    for (const [index, parameter] of parameters.entries()) {
+        new CfnResourcePolicy(scope, `${id}ReadPolicy${index}`, {
+            resourceArn: parameter.parameterArn,
+            policy: {
+                Version: "2012-10-17",
+                Statement: [
+                    {
+                        Effect: "Allow",
+                        Principal: { AWS: principals },
+                        Action: ["ssm:GetParameter"],
+                        Resource: parameter.parameterArn
+                    }
+                ]
+            }
+        });
+    }
+}
+function stackOfNode(node) {
+    const stack = node.scopes.find((a) => Stack.isStack(a));
+    if (!stack) {
+        throw new Error("exposedResource resource is not bound to a CDK Stack — cannot derive scope for SSM publishing.");
+    }
+    return stack;
+}

package/dist/lib/resources/aws/analytics/clickhouse.js

@@ -5,13 +5,14 @@ import { InstanceType, SubnetType, Connections, Port, UserData } from "aws-cdk-l
 import { AutoScalingGroup, Monitoring, BlockDeviceVolume, EbsDeviceVolumeType } from "aws-cdk-lib/aws-autoscaling";
 import { Duration, Stack } from "aws-cdk-lib";
 import { Construct } from "constructs";
-import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { LogGroup, RetentionDays } from "aws-cdk-lib/aws-logs";
 import { S3Bucket } from "../storage/s3.js";
 import { Secret } from "../secrets/secret.js";
 import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
 import { inferAmiHardwareType } from "../compute/ecsConstants.js";
 import { createClickHouseSecurityGroup } from "./clickhouseSecurityGroup.js";
 import { generateClickHouseUserData } from "./clickhouseUserData.js";
+import { createClickHouseAlarms } from "./clickhouseAlarms.js";
 import { CLICKHOUSE_CLUSTER_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, CLICKHOUSE_TASK_MEMORY_MIB, CLICKHOUSE_TASK_CPU_UNITS, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRETS_PREFIX, CLICKHOUSE_SECRET_NAMES, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_NAMESPACE, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "./clickhouseConstants.js";
 function createClickHouseSecret(scope, id, secretKey, description) {
     return new Secret(scope, id, {
@@ -237,7 +238,10 @@ export default class ClickHouse extends Construct {
         });
         // 11. Scheduled weekly backup to S3
         const backupDestUrl = `https://${backupBucket.bucketName}.s3.${Stack.of(this).region}.amazonaws.com/`;
-        const backupTask = new ScheduledEc2Task(this, "ClickHouseBackupTask", {
+        const backupTaskLogGroup = new LogGroup(this, "ClickHouseBackupTaskLogGroup", {
+            retention: RetentionDays.TWO_WEEKS
+        });
+        new ScheduledEc2Task(this, "ClickHouseBackupTask", {
             cluster,
             schedule: Schedule.expression(BACKUP_SCHEDULE),
             scheduledEc2TaskImageOptions: {
@@ -254,7 +258,7 @@ export default class ClickHouse extends Construct {
                 },
                 logDriver: LogDriver.awsLogs({
                     streamPrefix: "clickhouse-backup",
-                    logRetention: RetentionDays.TWO_WEEKS
+                    logGroup: backupTaskLogGroup
                 })
             },
             securityGroups: [securityGroup],
@@ -262,9 +266,11 @@ export default class ClickHouse extends Construct {
                 subnetType
             }
         });
-        // 12. Grant S3 write access to the backup task role
-        backupBucket.grantReadWrite(backupTask.taskDefinition.taskRole);
-        // 13. Grant secret read to execution role
+        // BACKUP DATABASE TO S3 runs inside the ClickHouse server process on the
+        // ASG instance, not the ephemeral backup task; the grant must therefore
+        // attach to the ASG instance role, not the task role.
+        backupBucket.grantReadWrite(asg.role);
+        // 12. Grant secret read to execution role
         const executionRole = taskDefinition.executionRole;
         if (!executionRole) {
             throw new Error("ClickHouse task definition has no execution role — cannot grant secret access");
@@ -273,7 +279,19 @@ export default class ClickHouse extends Construct {
         auditPasswordSecret.secret.grantRead(executionRole);
         backupPasswordSecret.secret.grantRead(executionRole);
         schemaPasswordSecret.secret.grantRead(executionRole);
-        // 14. Connections and outputs
+        if (props.alarmTopic) {
+            if (!props.webappLogGroup) {
+                throw new Error("ClickHouse: alarmTopic requires webappLogGroup so the stuck-merge metric filter can be wired.");
+            }
+            createClickHouseAlarms({
+                scope: this,
+                asg,
+                alarmTopic: props.alarmTopic,
+                webappLogGroup: props.webappLogGroup,
+                backupTaskLogGroup
+            });
+        }
+        // 13. Connections and outputs
         this.connections = new Connections({
             securityGroups: [securityGroup],
             defaultPort: Port.tcp(CLICKHOUSE_HTTP_PORT)

package/dist/lib/resources/aws/analytics/clickhouseAlarms.d.ts

@@ -0,0 +1,49 @@
+import { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
+import type { Construct } from "constructs";
+export interface ClickHouseAlarmThresholds {
+    /** EC2 host CPU % over 5 min. Default 90. */
+    cpuThreshold?: number;
+    /** EC2 host memory % over 5 min (requires CWAgent). Default 80. */
+    memoryThreshold?: number;
+    /** EBS root-volume disk % used. Default 70 (warn) — paired with critical at 85. */
+    diskWarnThreshold?: number;
+    /** EBS root-volume disk % used. Default 85. */
+    diskCriticalThreshold?: number;
+}
+export interface ClickHouseAlarmsProps {
+    scope: Construct;
+    asg: AutoScalingGroup;
+    alarmTopic: ITopic;
+    /**
+     * Webapp log group. Required to wire the stuck-merge alarm — `client.ts`
+     * emits `serverLogger.warn("ClickHouse", "Stuck merge detected")` when
+     * `system.merges` shows a merge elapsed > 30 min.
+     */
+    webappLogGroup: ILogGroup;
+    /**
+     * Backup-task log group. Required to wire the backup-failure alarm —
+     * `BACKUP DATABASE … TO S3(…)` emits `AccessDenied` / `S3Exception` lines
+     * when the IAM grant or bucket policy is misconfigured (silent before the
+     * alarm landed; the daily backup task exited non-zero with no signal).
+     */
+    backupTaskLogGroup: ILogGroup;
+    config?: ClickHouseAlarmThresholds;
+}
+/**
+ * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
+ * two log-driven alarms:
+ *
+ * - **Stuck merges** — `client.ts` polls `system.merges` every 5 min and logs
+ *   `serverLogger.warn("ClickHouse", "Stuck merge detected")` when elapsed
+ *   exceeds 30 min. The metric filter on the webapp log group emits a count
+ *   metric per match; the alarm fires on Sum >= 1 over 5 min × 2 evaluations.
+ * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup
+ *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
+ *   that masked the original IAM-grant misconfiguration (see
+ *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ */
+export declare function createClickHouseAlarms(props: ClickHouseAlarmsProps): Alarm[];

package/dist/lib/resources/aws/analytics/clickhouseAlarms.js

@@ -0,0 +1,140 @@
+import { Duration } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { FilterPattern, MetricFilter } from "aws-cdk-lib/aws-logs";
+import { ALARM_DEFAULTS, registerAlarm, buildAlarmDescription } from "../monitoring/alarmDefaults.js";
+const CLICKHOUSE_METRIC_NAMESPACE = "Fjall/ClickHouse";
+/**
+ * Single-node ClickHouse posture alarms. Covers host-level CPU + (optional)
+ * memory and disk via the CloudWatch Agent metric namespace `CWAgent`, plus
+ * two log-driven alarms:
+ *
+ * - **Stuck merges** — `client.ts` polls `system.merges` every 5 min and logs
+ *   `serverLogger.warn("ClickHouse", "Stuck merge detected")` when elapsed
+ *   exceeds 30 min. The metric filter on the webapp log group emits a count
+ *   metric per match; the alarm fires on Sum >= 1 over 5 min × 2 evaluations.
+ * - **Backup failures** — `AccessDenied` or `S3Exception` from the backup
+ *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
+ *   that masked the original IAM-grant misconfiguration (see
+ *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ */
+export function createClickHouseAlarms(props) {
+    const { scope, asg, alarmTopic, webappLogGroup, backupTaskLogGroup, config = {} } = props;
+    const alarms = [];
+    const snsAction = new SnsAction(alarmTopic);
+    const asgName = asg.autoScalingGroupName;
+    const cpuAlarm = new Alarm(scope, "ClickHouseCpuAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse host CPU utilisation exceeds threshold", undefined),
+        metric: new Metric({
+            namespace: "AWS/EC2",
+            metricName: "CPUUtilization",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Average"
+        }),
+        threshold: config.cpuThreshold ?? 90,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(cpuAlarm, snsAction, alarms);
+    const memoryAlarm = new Alarm(scope, "ClickHouseMemoryAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse host memory utilisation exceeds threshold (CWAgent)", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "mem_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+            statistic: "Average"
+        }),
+        threshold: config.memoryThreshold ?? 80,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(memoryAlarm, snsAction, alarms);
+    const diskWarnAlarm = new Alarm(scope, "ClickHouseDiskWarnAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse data volume above 70% used — plan growth response", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "disk_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: Duration.minutes(15),
+            statistic: "Average"
+        }),
+        threshold: config.diskWarnThreshold ?? 70,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(diskWarnAlarm, snsAction, alarms);
+    const diskCriticalAlarm = new Alarm(scope, "ClickHouseDiskCriticalAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse data volume above 85% used — imminent insert failures", undefined),
+        metric: new Metric({
+            namespace: "CWAgent",
+            metricName: "disk_used_percent",
+            dimensionsMap: { AutoScalingGroupName: asgName },
+            period: Duration.minutes(5),
+            statistic: "Average"
+        }),
+        threshold: config.diskCriticalThreshold ?? 85,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(diskCriticalAlarm, snsAction, alarms);
+    const stuckMergeMetricName = "ClickHouseStuckMergeCount";
+    new MetricFilter(scope, "ClickHouseStuckMergeMetricFilter", {
+        logGroup: webappLogGroup,
+        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
+        metricName: stuckMergeMetricName,
+        filterPattern: FilterPattern.literal('"Stuck merge detected"'),
+        metricValue: "1",
+        defaultValue: 0
+    });
+    const stuckMergeAlarm = new Alarm(scope, "ClickHouseStuckMergeAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse merge stuck > 30 min — investigate parts pressure or replica health", undefined),
+        metric: new Metric({
+            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+            metricName: stuckMergeMetricName,
+            period: Duration.minutes(5),
+            statistic: "Sum"
+        }),
+        threshold: 1,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(stuckMergeAlarm, snsAction, alarms);
+    const backupFailureMetricName = "ClickHouseBackupFailureCount";
+    new MetricFilter(scope, "ClickHouseBackupFailureMetricFilter", {
+        logGroup: backupTaskLogGroup,
+        metricNamespace: CLICKHOUSE_METRIC_NAMESPACE,
+        metricName: backupFailureMetricName,
+        filterPattern: FilterPattern.anyTerm("AccessDenied", "S3Exception"),
+        metricValue: "1",
+        defaultValue: 0
+    });
+    const backupFailureAlarm = new Alarm(scope, "ClickHouseBackupFailureAlarm", {
+        alarmDescription: buildAlarmDescription("ClickHouse BACKUP TO S3 emitted AccessDenied/S3Exception — verify ASG instance role grant on backup bucket", undefined),
+        metric: new Metric({
+            namespace: CLICKHOUSE_METRIC_NAMESPACE,
+            metricName: backupFailureMetricName,
+            period: Duration.hours(1),
+            statistic: "Sum"
+        }),
+        threshold: 1,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING
+    });
+    registerAlarm(backupFailureAlarm, snsAction, alarms);
+    return alarms;
+}

package/dist/lib/resources/aws/analytics/clickhouseConstants.d.ts

@@ -60,14 +60,14 @@ export declare const CLICKHOUSE_CLOUDMAP_SERVICE_NAME = "clickhouse";
 /** Materialised views that benefit from periodic OPTIMIZE to reduce part count at read time.
  *  These are not ReplacingMergeTree (no dedup needed) but un-merged parts force
  *  read-time aggregation which degrades query performance. */
-export declare const OPTIMISE_MV_TABLES: readonly ["metrics_hourly_mv", "metrics_daily_mv", "response_time_quantiles_hourly_mv", "deployment_duration_quantiles_daily_mv", "log_severity_hourly_mv", "compliance_score_daily_mv", "ai_usage_daily_mv"];
+export declare const OPTIMISE_MV_TABLES: readonly ["metrics_hourly_mv", "metrics_daily_mv", "response_time_quantiles_hourly_mv", "deployment_duration_quantiles_daily_mv", "log_severity_hourly_mv", "compliance_score_daily_mv", "ai_usage_daily_mv", "finding_daily_aggregate", "insight_pattern_dismissals"];
 /** Resource allocation for the lightweight optimise task. */
 export declare const OPTIMISE_TASK_MEMORY_MIB = 256;
 export declare const OPTIMISE_TASK_CPU_UNITS = 256;
-/** Automated backup schedule (weekly, Sunday 03:00 UTC — low-traffic window). */
-export declare const BACKUP_SCHEDULE = "cron(0 3 ? * SUN *)";
+/** Automated backup schedule (daily 03:00 UTC — low-traffic window). */
+export declare const BACKUP_SCHEDULE = "cron(0 3 * * ? *)";
 /** Resource allocation for the backup task (lightweight — clickhouse-client only). */
 export declare const BACKUP_TASK_MEMORY_MIB = 256;
 export declare const BACKUP_TASK_CPU_UNITS = 256;
-/** Backup object expiration: 14 days (retains 2 weekly snapshots). */
+/** Backup object expiration: 14 days (retains 14 daily snapshots). */
 export declare const BACKUP_RETENTION_DAYS = 14;

package/dist/lib/resources/aws/analytics/clickhouseConstants.js

@@ -73,15 +73,17 @@ export const OPTIMISE_MV_TABLES = [
     "deployment_duration_quantiles_daily_mv",
     "log_severity_hourly_mv",
     "compliance_score_daily_mv",
-    "ai_usage_daily_mv"
+    "ai_usage_daily_mv",
+    "finding_daily_aggregate",
+    "insight_pattern_dismissals"
 ];
 /** Resource allocation for the lightweight optimise task. */
 export const OPTIMISE_TASK_MEMORY_MIB = 256;
 export const OPTIMISE_TASK_CPU_UNITS = 256;
-/** Automated backup schedule (weekly, Sunday 03:00 UTC — low-traffic window). */
-export const BACKUP_SCHEDULE = "cron(0 3 ? * SUN *)";
+/** Automated backup schedule (daily 03:00 UTC — low-traffic window). */
+export const BACKUP_SCHEDULE = "cron(0 3 * * ? *)";
 /** Resource allocation for the backup task (lightweight — clickhouse-client only). */
 export const BACKUP_TASK_MEMORY_MIB = 256;
 export const BACKUP_TASK_CPU_UNITS = 256;
-/** Backup object expiration: 14 days (retains 2 weekly snapshots). */
+/** Backup object expiration: 14 days (retains 14 daily snapshots). */
 export const BACKUP_RETENTION_DAYS = 14;

package/dist/lib/resources/aws/analytics/clickhouseTypes.d.ts

@@ -1,6 +1,8 @@
 import type { IVpc, ISecurityGroup } from "aws-cdk-lib/aws-ec2";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import type { IBucket } from "aws-cdk-lib/aws-s3";
 import type { ISecret } from "aws-cdk-lib/aws-secretsmanager";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
 /** Props for the ClickHouse CDK construct. */
 export interface ClickHouseProps {
     /** VPC to deploy into. */
@@ -21,6 +23,16 @@ export interface ClickHouseProps {
      * If omitted, tiered storage is disabled (local-only).
      */
     r2Config?: ClickHouseR2Config;
+    /**
+     * SNS topic for CloudWatch alarms (CPU, memory, disk, stuck merges).
+     * If omitted, posture alarms are not created.
+     */
+    alarmTopic?: ITopic;
+    /**
+     * Webapp log group, required when `alarmTopic` is set so the stuck-merge
+     * metric filter can read the structured warning emitted by `client.ts`.
+     */
+    webappLogGroup?: ILogGroup;
 }
 /** Cloudflare R2 configuration for tiered storage and backups. */
 export interface ClickHouseR2Config {

package/dist/lib/resources/aws/analytics/clickhouseUserData.d.ts

@@ -2,4 +2,5 @@ export interface ClickHouseUserDataOptions {
     /** Cloudflare account ID for R2 cold storage. If omitted, local-only storage is used. */
     cfAccountId?: string;
 }
+export declare const USERS_CONFIG_XML = "<clickhouse>\n    <users>\n        <default>\n            <networks>\n                <ip>127.0.0.1</ip>\n                <ip>::1</ip>\n            </networks>\n        </default>\n    </users>\n    <profiles>\n        <default>\n            <optimize_move_to_prewhere>1</optimize_move_to_prewhere>\n            <!-- ALTER TABLE ... MODIFY TTL on a 30-day-partitioned table would otherwise\n                 trigger an immediate full-table rewrite (default = 1). On the t4g.medium\n                 box that's a merge-pool starvation event. Keep TTL changes lazy: parts\n                 re-evaluate TTL on their next natural merge, no forced rewrite. -->\n            <materialize_ttl_after_modify>0</materialize_ttl_after_modify>\n        </default>\n        <app_writer>\n            <max_threads>2</max_threads>\n            <max_insert_threads>1</max_insert_threads>\n            <max_concurrent_queries_for_user>4</max_concurrent_queries_for_user>\n            <log_queries_min_query_duration_ms>100</log_queries_min_query_duration_ms>\n            <optimize_move_to_prewhere>1</optimize_move_to_prewhere>\n            <use_query_condition_cache>1</use_query_condition_cache>\n            <!-- Re-enable skip indexes under FINAL (tenantQuery auto-FINALs RMT tables;\n                 default disables idx_aws_account, idx_application, idx_dedup, idx_fingerprint). -->\n            <use_skip_indexes_if_final>1</use_skip_indexes_if_final>\n            <!-- Tenant-isolation guards (ClickHouse PR #91065 fix). Belt-and-braces with the\n                 per-user SQL SETTINGS in 002-users.sql \u2014 keep both so `CREATE OR REPLACE USER`\n                 cannot regress this. Without these flags, FINAL queries on un-merged\n                 ReplacingMergeTree parts can leak across tenants. -->\n            <apply_row_policy_after_final>1</apply_row_policy_after_final>\n            <apply_prewhere_after_final>1</apply_prewhere_after_final>\n            <do_not_merge_across_partitions_select_final>1</do_not_merge_across_partitions_select_final>\n            <async_insert>1</async_insert>\n            <wait_for_async_insert>1</wait_for_async_insert>\n            <async_insert_max_data_size>10000000</async_insert_max_data_size>\n            <!-- Adaptive batching: tune flush window between 50 ms (low-latency rare inserts)\n                 and 2 s (absorbs bursts). A single fixed value is silently overridden by the\n                 adaptive algorithm. -->\n            <async_insert_busy_timeout_min_ms>50</async_insert_busy_timeout_min_ms>\n            <async_insert_busy_timeout_max_ms>2000</async_insert_busy_timeout_max_ms>\n            <async_insert_use_adaptive_busy_timeout>1</async_insert_use_adaptive_busy_timeout>\n            <!-- Server-side deduplication of async inserts. Latent retry safety net:\n                 if a producer retries the same insert window (network hiccup, lambda re-run,\n                 SQS redelivery), the second attempt collapses against the first. As of CH 26.1\n                 this also propagates end-to-end through dependent materialised views \u2014 without\n                 it, a retried insert could double-count in metrics_hourly_mv / log_severity_hourly_mv\n                 even if the base table dedups. CH pin is 26.3 so the propagation fix is in. -->\n            <async_insert_deduplicate>1</async_insert_deduplicate>\n            <input_format_parallel_parsing>0</input_format_parallel_parsing>\n            <output_format_parallel_formatting>0</output_format_parallel_formatting>\n            <!-- Lazy materialisation (CH 25.4+): for `SELECT * ... LIMIT N` shapes the planner\n                 reads only the columns needed to evaluate ORDER BY / WHERE, then fetches the\n                 remaining columns for the surviving N rows. Order-of-magnitude I/O reduction\n                 on dashboard queries (e.g. getLatestMetrics LIMIT 1 BY application_id). -->\n            <query_plan_optimize_lazy_materialization>1</query_plan_optimize_lazy_materialization>\n            <!-- Per-query memory cap (overrides server-wide max_memory_usage of 1 GB\n                 to give app_writer 2 GB headroom). Belt-and-braces with the inline\n                 SETTINGS in 002-users.sql so neither layer can drift alone. -->\n            <max_memory_usage>2000000000</max_memory_usage>\n            <max_memory_usage_for_user>2684354560</max_memory_usage_for_user>\n            <max_bytes_before_external_sort>536870912</max_bytes_before_external_sort>\n            <max_bytes_before_external_group_by>536870912</max_bytes_before_external_group_by>\n            <!-- Per-query caps. Belt-and-braces with the inline SETTINGS in\n                 002-users.sql so `CREATE OR REPLACE USER` cannot regress the bound. -->\n            <max_execution_time>30</max_execution_time>\n            <max_rows_to_read>10000000</max_rows_to_read>\n        </app_writer>\n        <audit_writer>\n            <max_threads>1</max_threads>\n            <max_insert_threads>1</max_insert_threads>\n            <max_concurrent_queries_for_user>2</max_concurrent_queries_for_user>\n            <max_memory_usage>500000000</max_memory_usage>\n            <max_execution_time>10</max_execution_time>\n            <async_insert>1</async_insert>\n            <wait_for_async_insert>1</wait_for_async_insert>\n        </audit_writer>\n        <backup_reader>\n            <max_threads>2</max_threads>\n            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>\n            <max_memory_usage>1000000000</max_memory_usage>\n            <max_execution_time>3600</max_execution_time>\n        </backup_reader>\n        <schema_admin>\n            <max_threads>2</max_threads>\n            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>\n            <max_memory_usage>1000000000</max_memory_usage>\n            <max_execution_time>1800</max_execution_time>\n        </schema_admin>\n    </profiles>\n    <quotas>\n        <tenant_default>\n            <interval>\n                <duration>3600</duration>\n                <queries>1000</queries>\n                <result_rows>10000000</result_rows>\n            </interval>\n        </tenant_default>\n    </quotas>\n</clickhouse>";
 export declare function generateClickHouseUserData(options?: ClickHouseUserDataOptions): string;

package/dist/lib/resources/aws/analytics/clickhouseUserData.js

@@ -96,7 +96,6 @@ function generateServerConfigXml(cfAccountId) {
     </merge_tree>
     <http_port>${CLICKHOUSE_HTTP_PORT}</http_port>
     <custom_settings_prefixes>current_</custom_settings_prefixes>
-    <allow_experimental_full_text_index>1</allow_experimental_full_text_index>
     <!-- HTTP keep-alive window. Must exceed @clickhouse/client idle_socket_ttl (15 s)
          so the client always closes the socket first. Prevents ECONNRESET on reuse. -->
     <keep_alive_timeout>30</keep_alive_timeout>
@@ -145,7 +144,7 @@ ${storageBlock}
     <processors_profile_log remove="1"/>
 </clickhouse>`;
 }
-const USERS_CONFIG_XML = `<clickhouse>
+export const USERS_CONFIG_XML = `<clickhouse>
     <users>
         <default>
             <networks>
@@ -157,15 +156,29 @@ const USERS_CONFIG_XML = `<clickhouse>
     <profiles>
         <default>
             <optimize_move_to_prewhere>1</optimize_move_to_prewhere>
+            <!-- ALTER TABLE ... MODIFY TTL on a 30-day-partitioned table would otherwise
+                 trigger an immediate full-table rewrite (default = 1). On the t4g.medium
+                 box that's a merge-pool starvation event. Keep TTL changes lazy: parts
+                 re-evaluate TTL on their next natural merge, no forced rewrite. -->
+            <materialize_ttl_after_modify>0</materialize_ttl_after_modify>
         </default>
         <app_writer>
             <max_threads>2</max_threads>
             <max_insert_threads>1</max_insert_threads>
+            <max_concurrent_queries_for_user>4</max_concurrent_queries_for_user>
+            <log_queries_min_query_duration_ms>100</log_queries_min_query_duration_ms>
             <optimize_move_to_prewhere>1</optimize_move_to_prewhere>
             <use_query_condition_cache>1</use_query_condition_cache>
             <!-- Re-enable skip indexes under FINAL (tenantQuery auto-FINALs RMT tables;
                  default disables idx_aws_account, idx_application, idx_dedup, idx_fingerprint). -->
             <use_skip_indexes_if_final>1</use_skip_indexes_if_final>
+            <!-- Tenant-isolation guards (ClickHouse PR #91065 fix). Belt-and-braces with the
+                 per-user SQL SETTINGS in 002-users.sql — keep both so \`CREATE OR REPLACE USER\`
+                 cannot regress this. Without these flags, FINAL queries on un-merged
+                 ReplacingMergeTree parts can leak across tenants. -->
+            <apply_row_policy_after_final>1</apply_row_policy_after_final>
+            <apply_prewhere_after_final>1</apply_prewhere_after_final>
+            <do_not_merge_across_partitions_select_final>1</do_not_merge_across_partitions_select_final>
             <async_insert>1</async_insert>
             <wait_for_async_insert>1</wait_for_async_insert>
             <async_insert_max_data_size>10000000</async_insert_max_data_size>
@@ -175,15 +188,53 @@ const USERS_CONFIG_XML = `<clickhouse>
             <async_insert_busy_timeout_min_ms>50</async_insert_busy_timeout_min_ms>
             <async_insert_busy_timeout_max_ms>2000</async_insert_busy_timeout_max_ms>
             <async_insert_use_adaptive_busy_timeout>1</async_insert_use_adaptive_busy_timeout>
+            <!-- Server-side deduplication of async inserts. Latent retry safety net:
+                 if a producer retries the same insert window (network hiccup, lambda re-run,
+                 SQS redelivery), the second attempt collapses against the first. As of CH 26.1
+                 this also propagates end-to-end through dependent materialised views — without
+                 it, a retried insert could double-count in metrics_hourly_mv / log_severity_hourly_mv
+                 even if the base table dedups. CH pin is 26.3 so the propagation fix is in. -->
+            <async_insert_deduplicate>1</async_insert_deduplicate>
             <input_format_parallel_parsing>0</input_format_parallel_parsing>
             <output_format_parallel_formatting>0</output_format_parallel_formatting>
+            <!-- Lazy materialisation (CH 25.4+): for \`SELECT * ... LIMIT N\` shapes the planner
+                 reads only the columns needed to evaluate ORDER BY / WHERE, then fetches the
+                 remaining columns for the surviving N rows. Order-of-magnitude I/O reduction
+                 on dashboard queries (e.g. getLatestMetrics LIMIT 1 BY application_id). -->
+            <query_plan_optimize_lazy_materialization>1</query_plan_optimize_lazy_materialization>
+            <!-- Per-query memory cap (overrides server-wide max_memory_usage of 1 GB
+                 to give app_writer 2 GB headroom). Belt-and-braces with the inline
+                 SETTINGS in 002-users.sql so neither layer can drift alone. -->
+            <max_memory_usage>2000000000</max_memory_usage>
             <max_memory_usage_for_user>2684354560</max_memory_usage_for_user>
             <max_bytes_before_external_sort>536870912</max_bytes_before_external_sort>
             <max_bytes_before_external_group_by>536870912</max_bytes_before_external_group_by>
+            <!-- Per-query caps. Belt-and-braces with the inline SETTINGS in
+                 002-users.sql so \`CREATE OR REPLACE USER\` cannot regress the bound. -->
+            <max_execution_time>30</max_execution_time>
+            <max_rows_to_read>10000000</max_rows_to_read>
         </app_writer>
-        <readonly>
-            <readonly>1</readonly>
-        </readonly>
+        <audit_writer>
+            <max_threads>1</max_threads>
+            <max_insert_threads>1</max_insert_threads>
+            <max_concurrent_queries_for_user>2</max_concurrent_queries_for_user>
+            <max_memory_usage>500000000</max_memory_usage>
+            <max_execution_time>10</max_execution_time>
+            <async_insert>1</async_insert>
+            <wait_for_async_insert>1</wait_for_async_insert>
+        </audit_writer>
+        <backup_reader>
+            <max_threads>2</max_threads>
+            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>
+            <max_memory_usage>1000000000</max_memory_usage>
+            <max_execution_time>3600</max_execution_time>
+        </backup_reader>
+        <schema_admin>
+            <max_threads>2</max_threads>
+            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>
+            <max_memory_usage>1000000000</max_memory_usage>
+            <max_execution_time>1800</max_execution_time>
+        </schema_admin>
     </profiles>
     <quotas>
         <tenant_default>