@fjall/components-infrastructure 0.89.5 → 0.89.6

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

@@ -0,0 +1,292 @@
+import { Cluster, Ec2TaskDefinition, NetworkMode, ContainerImage, LogDriver, AsgCapacityProvider, EcsOptimizedImage, Ec2Service, Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
+import { ScheduledEc2Task } from "aws-cdk-lib/aws-ecs-patterns";
+import { Schedule } from "aws-cdk-lib/aws-applicationautoscaling";
+import { InstanceType, SubnetType, Connections, Port, UserData } from "aws-cdk-lib/aws-ec2";
+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 { 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 { 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, {
+        secretName: `${CLICKHOUSE_SECRETS_PREFIX}/${secretKey}`,
+        description,
+        generateSecretString: CLICKHOUSE_SECRET_OPTIONS
+    });
+}
+/**
+ * ClickHouse analytics infrastructure.
+ *
+ * Creates a single-node ClickHouse instance on ECS EC2 with a dedicated
+ * gp3 EBS volume for data persistence. Designed for analytical workloads
+ * (cost aggregation, deployment metrics, audit logs) rather than OLTP.
+ */
+export default class ClickHouse extends Construct {
+    connections;
+    outputs;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const contextValue = this.node.tryGetContext("clickhouseInstanceType");
+        const instanceType = (typeof contextValue === "string" ? contextValue : undefined) ??
+            props.instanceType ??
+            DEFAULT_CLICKHOUSE_INSTANCE_TYPE;
+        // 1. Security group
+        const securityGroup = createClickHouseSecurityGroup(this, props.vpc, props.webappSecurityGroup);
+        // 2. Secrets Manager secrets (auto-generated passwords)
+        const appPasswordSecret = createClickHouseSecret(this, "ClickHouseAppPassword", CLICKHOUSE_SECRET_NAMES.APP_PASSWORD, "ClickHouse application user password");
+        const auditPasswordSecret = createClickHouseSecret(this, "ClickHouseAuditPassword", CLICKHOUSE_SECRET_NAMES.AUDIT_PASSWORD, "ClickHouse audit user password");
+        const backupPasswordSecret = createClickHouseSecret(this, "ClickHouseBackupPassword", CLICKHOUSE_SECRET_NAMES.BACKUP_PASSWORD, "ClickHouse backup user password");
+        const schemaPasswordSecret = createClickHouseSecret(this, "ClickHouseSchemaPassword", CLICKHOUSE_SECRET_NAMES.SCHEMA_PASSWORD, "ClickHouse schema migration user password");
+        // 3. ECS cluster with Cloud Map namespace for service discovery
+        const cluster = new Cluster(this, "ClickHouseCluster", {
+            clusterName: CLICKHOUSE_CLUSTER_NAME,
+            vpc: props.vpc,
+            defaultCloudMapNamespace: {
+                name: CLICKHOUSE_CLOUDMAP_NAMESPACE,
+                vpc: props.vpc
+            }
+        });
+        // 4. Auto Scaling Group with gp3 EBS volume
+        const amiHardwareType = inferAmiHardwareType(instanceType);
+        const hasNat = vpcHasNatGateways(props.vpc);
+        const subnetType = hasNat
+            ? SubnetType.PRIVATE_WITH_EGRESS
+            : SubnetType.PUBLIC;
+        const userData = UserData.custom(generateClickHouseUserData({
+            cfAccountId: props.r2Config?.accountId
+        }));
+        const asg = new AutoScalingGroup(this, "ClickHouseAsg", {
+            autoScalingGroupName: `${CLICKHOUSE_CLUSTER_NAME}-asg`,
+            vpc: props.vpc,
+            vpcSubnets: {
+                subnetType
+            },
+            securityGroup,
+            minCapacity: 1,
+            maxCapacity: 1,
+            desiredCapacity: 1,
+            instanceType: new InstanceType(instanceType),
+            machineImage: EcsOptimizedImage.amazonLinux2023(amiHardwareType),
+            instanceMonitoring: Monitoring.BASIC,
+            blockDevices: [
+                {
+                    deviceName: CLICKHOUSE_EBS_DEVICE_NAME,
+                    volume: BlockDeviceVolume.ebs(CLICKHOUSE_EBS_VOLUME_SIZE_GB, {
+                        volumeType: EbsDeviceVolumeType.GP3,
+                        iops: CLICKHOUSE_EBS_IOPS,
+                        throughput: CLICKHOUSE_EBS_THROUGHPUT_MBPS,
+                        encrypted: true
+                    })
+                }
+            ],
+            userData
+        });
+        // 5. Capacity provider
+        const capacityProvider = new AsgCapacityProvider(this, "ClickHouseCapacityProvider", {
+            autoScalingGroup: asg,
+            enableManagedDraining: true,
+            enableManagedTerminationProtection: false
+        });
+        cluster.addAsgCapacityProvider(capacityProvider);
+        // 6. Task definition with bind mount for EBS volume
+        const taskDefinition = new Ec2TaskDefinition(this, "ClickHouseTaskDefinition", {
+            family: CLICKHOUSE_CLUSTER_NAME,
+            networkMode: NetworkMode.AWS_VPC
+        });
+        taskDefinition.addVolume({
+            name: "clickhouse-data",
+            host: {
+                sourcePath: CLICKHOUSE_DATA_MOUNT_PATH
+            }
+        });
+        taskDefinition.addVolume({
+            name: "clickhouse-config",
+            host: {
+                sourcePath: `${CLICKHOUSE_DATA_MOUNT_PATH}/${CLICKHOUSE_CONFIG_SUBDIR}`
+            }
+        });
+        taskDefinition.addVolume({
+            name: "clickhouse-users",
+            host: {
+                sourcePath: `${CLICKHOUSE_DATA_MOUNT_PATH}/${CLICKHOUSE_USERS_SUBDIR}`
+            }
+        });
+        // 7. Container
+        const container = taskDefinition.addContainer("clickhouse", {
+            image: ContainerImage.fromRegistry(CLICKHOUSE_IMAGE),
+            memoryLimitMiB: CLICKHOUSE_TASK_MEMORY_MIB,
+            cpu: CLICKHOUSE_TASK_CPU_UNITS,
+            logging: LogDriver.awsLogs({
+                streamPrefix: "clickhouse",
+                logRetention: RetentionDays.TWO_WEEKS
+            }),
+            healthCheck: {
+                command: [
+                    "CMD-SHELL",
+                    `curl -f http://localhost:${CLICKHOUSE_HTTP_PORT}/?query=SELECT%201 || exit 1`
+                ],
+                interval: Duration.seconds(CLICKHOUSE_HEALTH_CHECK.INTERVAL_SECONDS),
+                timeout: Duration.seconds(CLICKHOUSE_HEALTH_CHECK.TIMEOUT_SECONDS),
+                retries: CLICKHOUSE_HEALTH_CHECK.RETRIES,
+                startPeriod: Duration.seconds(CLICKHOUSE_HEALTH_CHECK.START_PERIOD_SECONDS)
+            },
+            secrets: {
+                CLICKHOUSE_APP_PASSWORD: EcsSecret.fromSecretsManager(appPasswordSecret.secret),
+                CLICKHOUSE_AUDIT_PASSWORD: EcsSecret.fromSecretsManager(auditPasswordSecret.secret),
+                ...(props.r2Config
+                    ? {
+                        R2_ACCESS_KEY: EcsSecret.fromSecretsManager(props.r2Config.accessKeySecret),
+                        R2_SECRET_KEY: EcsSecret.fromSecretsManager(props.r2Config.secretKeySecret)
+                    }
+                    : {})
+            },
+            portMappings: [
+                { containerPort: CLICKHOUSE_HTTP_PORT, hostPort: CLICKHOUSE_HTTP_PORT },
+                {
+                    containerPort: CLICKHOUSE_NATIVE_PORT,
+                    hostPort: CLICKHOUSE_NATIVE_PORT
+                },
+                {
+                    containerPort: CLICKHOUSE_PROMETHEUS_PORT,
+                    hostPort: CLICKHOUSE_PROMETHEUS_PORT
+                }
+            ]
+        });
+        container.addMountPoints({
+            sourceVolume: "clickhouse-data",
+            containerPath: "/var/lib/clickhouse",
+            readOnly: false
+        }, {
+            sourceVolume: "clickhouse-config",
+            containerPath: "/etc/clickhouse-server/config.d",
+            readOnly: true
+        }, {
+            sourceVolume: "clickhouse-users",
+            containerPath: "/etc/clickhouse-server/users.d",
+            readOnly: true
+        });
+        // 8. ECS service with Cloud Map registration for optimise task discovery
+        const clickHouseHost = `${CLICKHOUSE_CLOUDMAP_SERVICE_NAME}.${CLICKHOUSE_CLOUDMAP_NAMESPACE}`;
+        new Ec2Service(this, "ClickHouseService", {
+            cluster,
+            taskDefinition,
+            desiredCount: 1,
+            capacityProviderStrategies: [
+                {
+                    capacityProvider: capacityProvider.capacityProviderName,
+                    weight: 1
+                }
+            ],
+            circuitBreaker: { rollback: true },
+            cloudMapOptions: {
+                name: CLICKHOUSE_CLOUDMAP_SERVICE_NAME
+            }
+        });
+        // 9. Scheduled OPTIMIZE TABLE FINAL task (deduplicates ReplacingMergeTree tables)
+        const optimiseQuery = [
+            ...REPLACING_MERGE_TREE_TABLES.map((table) => `OPTIMIZE TABLE analytics.${table} FINAL`),
+            ...OPTIMISE_MV_TABLES.map((table) => `OPTIMIZE TABLE analytics.${table}`)
+        ].join("; ");
+        new ScheduledEc2Task(this, "ClickHouseOptimiseTask", {
+            cluster,
+            schedule: Schedule.expression(OPTIMISE_FINAL_SCHEDULE),
+            scheduledEc2TaskImageOptions: {
+                image: ContainerImage.fromRegistry(CLICKHOUSE_IMAGE),
+                memoryLimitMiB: OPTIMISE_TASK_MEMORY_MIB,
+                cpu: OPTIMISE_TASK_CPU_UNITS,
+                command: [
+                    "clickhouse-client",
+                    "--host",
+                    clickHouseHost,
+                    "--port",
+                    String(CLICKHOUSE_NATIVE_PORT),
+                    "--user",
+                    "schema_admin",
+                    "--query",
+                    `${optimiseQuery};`
+                ],
+                secrets: {
+                    CLICKHOUSE_PASSWORD: EcsSecret.fromSecretsManager(schemaPasswordSecret.secret)
+                },
+                logDriver: LogDriver.awsLogs({
+                    streamPrefix: "clickhouse-optimise",
+                    logRetention: RetentionDays.ONE_WEEK
+                })
+            },
+            securityGroups: [securityGroup],
+            subnetSelection: {
+                subnetType
+            }
+        });
+        // 10. S3 bucket for weekly backups
+        const backupBucket = new S3Bucket(this, "ClickHouseBackupBucket", {
+            versioned: true,
+            lifecycleRules: [
+                {
+                    enabled: true,
+                    expiration: Duration.days(BACKUP_RETENTION_DAYS),
+                    noncurrentVersionExpiration: Duration.days(BACKUP_RETENTION_DAYS)
+                }
+            ]
+        });
+        // 11. Scheduled weekly backup to S3
+        const backupDestUrl = `https://${backupBucket.bucketName}.s3.${Stack.of(this).region}.amazonaws.com/`;
+        const backupTask = new ScheduledEc2Task(this, "ClickHouseBackupTask", {
+            cluster,
+            schedule: Schedule.expression(BACKUP_SCHEDULE),
+            scheduledEc2TaskImageOptions: {
+                image: ContainerImage.fromRegistry(CLICKHOUSE_IMAGE),
+                memoryLimitMiB: BACKUP_TASK_MEMORY_MIB,
+                cpu: BACKUP_TASK_CPU_UNITS,
+                command: [
+                    "sh",
+                    "-c",
+                    `STAMP=$(date +%Y%m%d-%H%M%S) && clickhouse-client --host ${clickHouseHost} --port ${CLICKHOUSE_NATIVE_PORT} --user backup_reader --password "$CLICKHOUSE_BACKUP_PASSWORD" --query "BACKUP DATABASE analytics TO S3('${backupDestUrl}weekly-$STAMP/')"`
+                ],
+                secrets: {
+                    CLICKHOUSE_BACKUP_PASSWORD: EcsSecret.fromSecretsManager(backupPasswordSecret.secret)
+                },
+                logDriver: LogDriver.awsLogs({
+                    streamPrefix: "clickhouse-backup",
+                    logRetention: RetentionDays.TWO_WEEKS
+                })
+            },
+            securityGroups: [securityGroup],
+            subnetSelection: {
+                subnetType
+            }
+        });
+        // 12. Grant S3 write access to the backup task role
+        backupBucket.grantReadWrite(backupTask.taskDefinition.taskRole);
+        // 13. 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");
+        }
+        appPasswordSecret.secret.grantRead(executionRole);
+        auditPasswordSecret.secret.grantRead(executionRole);
+        backupPasswordSecret.secret.grantRead(executionRole);
+        schemaPasswordSecret.secret.grantRead(executionRole);
+        // 14. Connections and outputs
+        this.connections = new Connections({
+            securityGroups: [securityGroup],
+            defaultPort: Port.tcp(CLICKHOUSE_HTTP_PORT)
+        });
+        this.outputs = {
+            securityGroup,
+            backupBucket,
+            secrets: {
+                appPassword: appPasswordSecret.secret,
+                auditPassword: auditPasswordSecret.secret,
+                backupPassword: backupPasswordSecret.secret,
+                schemaPassword: schemaPasswordSecret.secret
+            }
+        };
+    }
+}

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

@@ -0,0 +1,73 @@
+/** Cluster/task family name used for ECS resources. */
+export declare const CLICKHOUSE_CLUSTER_NAME = "clickhouse-analytics";
+/** Default EC2 instance type for ClickHouse (Graviton — best cost/performance). */
+export declare const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "t4g.medium";
+/** ClickHouse container image. */
+export declare const CLICKHOUSE_IMAGE = "clickhouse/clickhouse-server:26.3-alpine";
+/** EBS volume configuration. */
+export declare const CLICKHOUSE_EBS_VOLUME_SIZE_GB = 80;
+export declare const CLICKHOUSE_EBS_IOPS = 3000;
+export declare const CLICKHOUSE_EBS_THROUGHPUT_MBPS = 125;
+/** ECS task resource allocation (t4g.medium = 4 GB total). */
+export declare const CLICKHOUSE_TASK_MEMORY_MIB = 3072;
+export declare const CLICKHOUSE_TASK_CPU_UNITS = 1024;
+/** ClickHouse ports. */
+export declare const CLICKHOUSE_HTTP_PORT = 8123;
+export declare const CLICKHOUSE_NATIVE_PORT = 9000;
+export declare const CLICKHOUSE_PROMETHEUS_PORT = 9363;
+/** EBS device name for the data volume (must match user data script). */
+export declare const CLICKHOUSE_EBS_DEVICE_NAME = "/dev/xvdf";
+/** EBS mount path on the EC2 host. */
+export declare const CLICKHOUSE_DATA_MOUNT_PATH = "/mnt/clickhouse-data";
+/** Secrets Manager path prefix. */
+export declare const CLICKHOUSE_SECRETS_PREFIX = "fjall/clickhouse";
+/** Secret names (under the prefix). */
+export declare const CLICKHOUSE_SECRET_NAMES: {
+    readonly APP_PASSWORD: "app-password";
+    readonly AUDIT_PASSWORD: "audit-password";
+    readonly BACKUP_PASSWORD: "backup-password";
+    readonly SCHEMA_PASSWORD: "schema-password";
+};
+/** Shared secret generation options (all ClickHouse users share the same policy). */
+export declare const CLICKHOUSE_SECRET_OPTIONS: {
+    readonly excludePunctuation: true;
+    readonly passwordLength: 32;
+};
+/** Health check configuration. */
+export declare const CLICKHOUSE_HEALTH_CHECK: {
+    readonly INTERVAL_SECONDS: 30;
+    readonly TIMEOUT_SECONDS: 5;
+    readonly RETRIES: 3;
+    readonly START_PERIOD_SECONDS: 60;
+};
+/** OPTIMIZE TABLE FINAL schedule.
+ *  RMT tables carry min_age_to_force_merge_seconds=600 so the engine already merges
+ *  old parts within 10 min; this task is a safety net for MVs (no engine-level setting)
+ *  and for ReplacingMergeTree dedup under skewed write patterns. 6 hours is sufficient. */
+export declare const OPTIMISE_FINAL_SCHEDULE = "rate(6 hours)";
+/** Tables requiring periodic OPTIMIZE FINAL (ReplacingMergeTree only).
+ *  Keep in sync with REPLACING_MERGE_TREE_TABLES in
+ *  webapp/app/.server/lib/clickhouse/tenantQuery.ts (auto-FINAL). */
+export declare const REPLACING_MERGE_TREE_TABLES: readonly ["application_metrics", "cost_records", "log_fingerprints", "insights", "asset_inventory"];
+/** Subdirectory on the EBS volume for server config files (must match CDK volume mount). */
+export declare const CLICKHOUSE_CONFIG_SUBDIR = "server-config.d";
+/** Subdirectory on the EBS volume for users config files (must match CDK volume mount). */
+export declare const CLICKHOUSE_USERS_SUBDIR = "server-users.d";
+/** Cloud Map namespace for ClickHouse service discovery. */
+export declare const CLICKHOUSE_CLOUDMAP_NAMESPACE = "clickhouse.local";
+/** Cloud Map service name (resolves to clickhouse.clickhouse.local). */
+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"];
+/** 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 *)";
+/** 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). */
+export declare const BACKUP_RETENTION_DAYS = 14;

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

@@ -0,0 +1,87 @@
+/** Cluster/task family name used for ECS resources. */
+export const CLICKHOUSE_CLUSTER_NAME = "clickhouse-analytics";
+/** Default EC2 instance type for ClickHouse (Graviton — best cost/performance). */
+export const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "t4g.medium";
+/** ClickHouse container image. */
+export const CLICKHOUSE_IMAGE = "clickhouse/clickhouse-server:26.3-alpine";
+/** EBS volume configuration. */
+export const CLICKHOUSE_EBS_VOLUME_SIZE_GB = 80;
+export const CLICKHOUSE_EBS_IOPS = 3000;
+export const CLICKHOUSE_EBS_THROUGHPUT_MBPS = 125;
+/** ECS task resource allocation (t4g.medium = 4 GB total). */
+export const CLICKHOUSE_TASK_MEMORY_MIB = 3072;
+export const CLICKHOUSE_TASK_CPU_UNITS = 1024;
+/** ClickHouse ports. */
+export const CLICKHOUSE_HTTP_PORT = 8123;
+export const CLICKHOUSE_NATIVE_PORT = 9000;
+export const CLICKHOUSE_PROMETHEUS_PORT = 9363;
+/** EBS device name for the data volume (must match user data script). */
+export const CLICKHOUSE_EBS_DEVICE_NAME = "/dev/xvdf";
+/** EBS mount path on the EC2 host. */
+export const CLICKHOUSE_DATA_MOUNT_PATH = "/mnt/clickhouse-data";
+/** Secrets Manager path prefix. */
+export const CLICKHOUSE_SECRETS_PREFIX = "fjall/clickhouse";
+/** Secret names (under the prefix). */
+export const CLICKHOUSE_SECRET_NAMES = {
+    APP_PASSWORD: "app-password",
+    AUDIT_PASSWORD: "audit-password",
+    BACKUP_PASSWORD: "backup-password",
+    SCHEMA_PASSWORD: "schema-password"
+};
+/** Shared secret generation options (all ClickHouse users share the same policy). */
+export const CLICKHOUSE_SECRET_OPTIONS = {
+    excludePunctuation: true,
+    passwordLength: 32
+};
+/** Health check configuration. */
+export const CLICKHOUSE_HEALTH_CHECK = {
+    INTERVAL_SECONDS: 30,
+    TIMEOUT_SECONDS: 5,
+    RETRIES: 3,
+    START_PERIOD_SECONDS: 60
+};
+/** OPTIMIZE TABLE FINAL schedule.
+ *  RMT tables carry min_age_to_force_merge_seconds=600 so the engine already merges
+ *  old parts within 10 min; this task is a safety net for MVs (no engine-level setting)
+ *  and for ReplacingMergeTree dedup under skewed write patterns. 6 hours is sufficient. */
+export const OPTIMISE_FINAL_SCHEDULE = "rate(6 hours)";
+/** Tables requiring periodic OPTIMIZE FINAL (ReplacingMergeTree only).
+ *  Keep in sync with REPLACING_MERGE_TREE_TABLES in
+ *  webapp/app/.server/lib/clickhouse/tenantQuery.ts (auto-FINAL). */
+export const REPLACING_MERGE_TREE_TABLES = [
+    "application_metrics",
+    "cost_records",
+    "log_fingerprints",
+    "insights",
+    "asset_inventory"
+];
+/** Subdirectory on the EBS volume for server config files (must match CDK volume mount). */
+export const CLICKHOUSE_CONFIG_SUBDIR = "server-config.d";
+/** Subdirectory on the EBS volume for users config files (must match CDK volume mount). */
+export const CLICKHOUSE_USERS_SUBDIR = "server-users.d";
+/** Cloud Map namespace for ClickHouse service discovery. */
+export const CLICKHOUSE_CLOUDMAP_NAMESPACE = "clickhouse.local";
+/** Cloud Map service name (resolves to clickhouse.clickhouse.local). */
+export 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 const OPTIMISE_MV_TABLES = [
+    "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"
+];
+/** 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 *)";
+/** 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). */
+export const BACKUP_RETENTION_DAYS = 14;

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

@@ -0,0 +1,13 @@
+import { type ISecurityGroup, type IVpc } from "aws-cdk-lib/aws-ec2";
+import type { Construct } from "constructs";
+import { SecurityGroup } from "../networking/securityGroup.js";
+/**
+ * Creates the ClickHouse security group.
+ *
+ * Inbound:
+ *   - TCP 8123 from webapp ECS service SG (HTTP queries)
+ *
+ * Outbound:
+ *   - HTTPS 443 to 0.0.0.0/0 (R2 endpoint + Secrets Manager)
+ */
+export declare function createClickHouseSecurityGroup(scope: Construct, vpc: IVpc, webappSecurityGroup: ISecurityGroup): SecurityGroup;

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

@@ -0,0 +1,28 @@
+import { Peer, Port } from "aws-cdk-lib/aws-ec2";
+import { SecurityGroup } from "../networking/securityGroup.js";
+import { CLICKHOUSE_HTTP_PORT, CLICKHOUSE_NATIVE_PORT } from "./clickhouseConstants.js";
+/**
+ * Creates the ClickHouse security group.
+ *
+ * Inbound:
+ *   - TCP 8123 from webapp ECS service SG (HTTP queries)
+ *
+ * Outbound:
+ *   - HTTPS 443 to 0.0.0.0/0 (R2 endpoint + Secrets Manager)
+ */
+export function createClickHouseSecurityGroup(scope, vpc, webappSecurityGroup) {
+    const sg = new SecurityGroup(scope, "ClickHouseSecurityGroup", {
+        vpc,
+        description: "Security group for ClickHouse analytics instance",
+        allowAllOutbound: false
+    });
+    // Inbound: HTTP API from webapp
+    sg.addIngressRule(webappSecurityGroup, Port.tcp(CLICKHOUSE_HTTP_PORT), "ClickHouse HTTP API from webapp ECS service");
+    // Inbound: Native protocol from optimise scheduled task (same SG, self-referencing)
+    sg.addIngressRule(sg, Port.tcp(CLICKHOUSE_NATIVE_PORT), "ClickHouse native protocol from optimise task");
+    // Outbound: HTTPS for R2 cold storage and Secrets Manager
+    sg.addEgressRule(Peer.anyIpv4(), Port.tcp(443), "HTTPS to R2 and Secrets Manager endpoints");
+    // Outbound: Native protocol to ClickHouse (optimise task connection)
+    sg.addEgressRule(sg, Port.tcp(CLICKHOUSE_NATIVE_PORT), "ClickHouse native protocol for optimise task");
+    return sg;
+}

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

@@ -0,0 +1,47 @@
+import type { IVpc, ISecurityGroup } from "aws-cdk-lib/aws-ec2";
+import type { IBucket } from "aws-cdk-lib/aws-s3";
+import type { ISecret } from "aws-cdk-lib/aws-secretsmanager";
+/** Props for the ClickHouse CDK construct. */
+export interface ClickHouseProps {
+    /** VPC to deploy into. */
+    vpc: IVpc;
+    /**
+     * EC2 instance type for ClickHouse.
+     * Overridden by CDK context parameter `clickhouseInstanceType` if set.
+     * Default: t4g.medium (4 GB RAM).
+     */
+    instanceType?: string;
+    /**
+     * Security group of the webapp ECS service.
+     * Used to allow inbound HTTP (8123) from the webapp.
+     */
+    webappSecurityGroup: ISecurityGroup;
+    /**
+     * R2 configuration for cold storage.
+     * If omitted, tiered storage is disabled (local-only).
+     */
+    r2Config?: ClickHouseR2Config;
+}
+/** Cloudflare R2 configuration for tiered storage and backups. */
+export interface ClickHouseR2Config {
+    /** Cloudflare account ID. */
+    accountId: string;
+    /** R2 access key (stored in Secrets Manager). */
+    accessKeySecret: ISecret;
+    /** R2 secret key (stored in Secrets Manager). */
+    secretKeySecret: ISecret;
+}
+/** Outputs from the ClickHouse construct for use by other constructs. */
+export interface ClickHouseOutputs {
+    /** Security group for the ClickHouse instance (for connection rules). */
+    securityGroup: ISecurityGroup;
+    /** S3 bucket for weekly automated backups (for restore operations). */
+    backupBucket: IBucket;
+    /** Secrets Manager secrets for ClickHouse passwords. */
+    secrets: {
+        appPassword: ISecret;
+        auditPassword: ISecret;
+        backupPassword: ISecret;
+        schemaPassword: ISecret;
+    };
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+export interface ClickHouseUserDataOptions {
+    /** Cloudflare account ID for R2 cold storage. If omitted, local-only storage is used. */
+    cfAccountId?: string;
+}
+export declare function generateClickHouseUserData(options?: ClickHouseUserDataOptions): string;