@fjall/components-infrastructure 0.96.0 → 0.99.3

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

@@ -0,0 +1,601 @@
+import { CLICKHOUSE_MANAGED_USERS_ENV } from "@fjall/util/migration";
+import { Annotations, CfnOutput, Duration, Fn, Stack } from "aws-cdk-lib";
+import { Connections, Port, UserData } from "aws-cdk-lib/aws-ec2";
+import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
+import { ContainerImage, EcsOptimizedImage, NetworkMode, Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
+import { ManagedPolicy, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Source } from "aws-cdk-lib/aws-s3-deployment";
+import { BucketDeployment } from "../../resources/aws/storage/bucketDeployment.js";
+import { AwsCustomResourcePolicy, PhysicalResourceId } from "aws-cdk-lib/custom-resources";
+import { AwsCustomResource } from "../../resources/aws/utilities/awsCustomResource.js";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { Construct } from "constructs";
+import { z } from "zod";
+import App from "../../app.js";
+import { S3Bucket } from "../../resources/aws/storage/s3.js";
+import { Secret } from "../../resources/aws/secrets/secret.js";
+import { LogGroup } from "../../resources/aws/logging/logGroup.js";
+import { createClickHouseSecurityGroup } from "../../resources/aws/database/clickhouseSecurityGroup.js";
+import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUsersConfigXml } from "../../resources/aws/database/clickhouseUserData.js";
+import { toPascalCase } from "../../utils/capitaliseString.js";
+import { ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, ClickHouseDefaultProfiles, PROFILE_NAME_PATTERN } from "../../resources/aws/database/clickhouseSchemas.js";
+import { inferAmiHardwareType } from "../../resources/aws/compute/ecsConstants.js";
+import { CLICKHOUSE_DATABASE_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, CLICKHOUSE_TASK_MEMORY_MIB, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_SERVER_ROLE_TAG, clickHouseUserSecretName, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_STOP_TIMEOUT_SECONDS, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, userPasswordEnvName, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, CLICKHOUSE_SERVER_CONTAINER_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "../../resources/aws/database/clickhouseConstants.js";
+import { EcsCompute } from "./computeEcs.js";
+/**
+ * Resolve the ECS desired task count for the ClickHouse service.
+ *
+ * Precedence: CDK context (`clickhouseDesiredCount`) > prop > default 1.
+ *
+ * Context values arrive as strings (`--context clickhouseDesiredCount=0`) or
+ * numbers (when set in `cdk.json`); both shapes parse here. Empty-string and
+ * non-finite values fall through to the prop / default — closes the
+ * `??`-empty-string trap (CDK consumers can legitimately set `--context X=`
+ * to clear a stale value).
+ */
+function resolveClickHouseDesiredCount(contextValue, propValue) {
+    if (typeof contextValue === "number" && Number.isFinite(contextValue)) {
+        return contextValue;
+    }
+    if (typeof contextValue === "string" && contextValue !== "") {
+        const parsed = parseInt(contextValue, 10);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    if (propValue !== undefined)
+        return propValue;
+    return 1;
+}
+/**
+ * Narrow `T | undefined` to `T`. Used at the 3 sites where a `Map.get(...)` /
+ * `Array.find(...)` result is structurally undefined-able but invariants
+ * earlier in the constructor guarantee a value. The thrown message names the
+ * invariant so the rare violation is debuggable.
+ */
+function expectDefined(value, invariant) {
+    if (value === undefined) {
+        throw new Error(`ClickHouseDatabase: unreachable — ${invariant}`);
+    }
+    return value;
+}
+function createClickHouseUserSecret(scope, name) {
+    return new Secret(scope, `ClickHouseUser${toPascalCase(name)}`, {
+        secretName: clickHouseUserSecretName(name),
+        description: `ClickHouse ${name} user password`,
+        generateSecretString: {
+            ...CLICKHOUSE_SECRET_OPTIONS,
+            secretStringTemplate: JSON.stringify({ username: name }),
+            generateStringKey: "password"
+        }
+    });
+}
+/**
+ * ClickHouse analytics database wrapper implementing IClickHouseDatabase.
+ *
+ * Composes `EcsCompute` directly per Phase 5e D7 — one EC2-pinned service
+ * (single-instance, AWS_VPC mode, Cloud Map registered) plus two scheduled
+ * tasks (optimise + backup). Per-role secrets, dual S3 buckets, and 10
+ * CfnOutputs are owned by `ClickHouseDatabase` itself; every taggable
+ * resource routes through its Fjall wrapper (AC45d-g).
+ */
+export class ClickHouseDatabase extends Construct {
+    databaseType = "ClickHouse";
+    connectorType = "relational";
+    additionalTcpPorts = [CLICKHOUSE_NATIVE_PORT];
+    id;
+    connections;
+    #users;
+    #schemaAdmin;
+    #managedPasswordNames;
+    #backupBucket;
+    #coldTierBucket;
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.id = id;
+        if (!props.vpc) {
+            throw new Error("VPC is required for ClickHouse database");
+        }
+        const vpc = props.vpc;
+        const schemaAdminParse = ClickHouseSchemaAdminSchema.safeParse(props.schemaAdmin);
+        if (!schemaAdminParse.success) {
+            throw new Error(`ClickHouseDatabase: invalid schemaAdmin: prop — ${schemaAdminParse.error.message}`);
+        }
+        const schemaAdmin = schemaAdminParse.data;
+        const managedPasswordsParse = z
+            .array(ManagedPasswordNameSchema)
+            .default(() => [])
+            .safeParse(props.managedPasswords);
+        if (!managedPasswordsParse.success) {
+            throw new Error(`ClickHouseDatabase: invalid managedPasswords: prop — ${managedPasswordsParse.error.message}`);
+        }
+        const managedPasswords = managedPasswordsParse.data;
+        const profiles = props.profiles ?? ClickHouseDefaultProfiles;
+        const ProfilesRecordSchema = z.record(z
+            .string()
+            .regex(PROFILE_NAME_PATTERN, "Profile name must be lowercase snake_case"), ProfileSpecSchema);
+        const profilesParse = ProfilesRecordSchema.safeParse(profiles);
+        if (!profilesParse.success) {
+            throw new Error(`ClickHouseDatabase: invalid profiles: prop — ${profilesParse.error.message}`);
+        }
+        if (!(schemaAdmin.profile in profiles)) {
+            throw new Error(`ClickHouseDatabase: schemaAdmin '${schemaAdmin.name}' references unknown profile '${schemaAdmin.profile}'. ` +
+                `Known profiles: ${Object.keys(profiles).join(", ")}`);
+        }
+        const seenNames = new Set([schemaAdmin.name]);
+        for (const name of managedPasswords) {
+            if (seenNames.has(name)) {
+                throw new Error(`ClickHouseDatabase: duplicate user name '${name}' — collides with schemaAdmin or another managedPasswords entry`);
+            }
+            seenNames.add(name);
+        }
+        const allUserNames = [
+            schemaAdmin.name,
+            ...managedPasswords
+        ];
+        const contextValue = this.node.tryGetContext("clickhouseInstanceType");
+        const contextInstanceType = typeof contextValue === "string" && contextValue !== ""
+            ? contextValue
+            : undefined;
+        const propInstanceType = props.instanceType !== undefined && props.instanceType !== ""
+            ? props.instanceType
+            : undefined;
+        const instanceType = contextInstanceType ??
+            propInstanceType ??
+            DEFAULT_CLICKHOUSE_INSTANCE_TYPE;
+        const desiredCount = resolveClickHouseDesiredCount(this.node.tryGetContext("clickhouseDesiredCount"), props.desiredCount);
+        const optimiseEnabled = props.optimiseSchedule !== false;
+        const backupEnabled = props.backupSchedule !== false;
+        const optimiseSchedule = typeof props.optimiseSchedule === "string"
+            ? props.optimiseSchedule
+            : OPTIMISE_FINAL_SCHEDULE;
+        const backupSchedule = typeof props.backupSchedule === "string"
+            ? props.backupSchedule
+            : BACKUP_SCHEDULE;
+        const backupRetentionDays = props.backupRetentionDays ?? BACKUP_RETENTION_DAYS;
+        if (props.backupRetentionDays !== undefined &&
+            (props.backupRetentionDays < 1 || props.backupRetentionDays > 3650)) {
+            throw new Error(`ClickHouseDatabase: backupRetentionDays must be between 1 and 3650; got ${props.backupRetentionDays}.`);
+        }
+        const securityGroup = createClickHouseSecurityGroup(this, vpc, CLICKHOUSE_NATIVE_PORT);
+        const userSecrets = new Map();
+        for (const name of allUserNames) {
+            userSecrets.set(name, createClickHouseUserSecret(this, name));
+        }
+        this.#users = userSecrets;
+        this.#schemaAdmin = schemaAdmin;
+        this.#managedPasswordNames = managedPasswords;
+        const backupBucket = props.backupBucket ??
+            new S3Bucket(this, "ClickHouseBackupBucket", {
+                versioned: true,
+                lifecycleRules: [
+                    {
+                        enabled: true,
+                        prefix: "backup/",
+                        expiration: Duration.days(backupRetentionDays),
+                        noncurrentVersionExpiration: Duration.days(backupRetentionDays)
+                    }
+                ]
+            });
+        const coldTierEnabled = props.coldTier !== false;
+        const coldTierBucket = coldTierEnabled
+            ? (props.coldTierBucket ??
+                new S3Bucket(this, "ClickHouseColdTierBucket", {
+                    versioned: false
+                }))
+            : undefined;
+        this.#backupBucket = backupBucket;
+        this.#coldTierBucket = coldTierBucket;
+        const backupTaskLogGroup = backupEnabled
+            ? new LogGroup(this, "ClickHouseBackupTaskLogGroup", {
+                retention: RetentionDays.TWO_WEEKS
+            })
+            : undefined;
+        const userData = UserData.custom(buildClickHouseUserData({
+            backupBucketName: backupBucket.bucketName,
+            backupBucketRegion: Stack.of(this).region,
+            ...(coldTierBucket !== undefined && {
+                coldTier: {
+                    bucketName: coldTierBucket.bucketName,
+                    region: Stack.of(this).region
+                }
+            })
+        }));
+        // Source.data wraps the content in a zip; the default `extract: true`
+        // unpacks it at the destination so the key is `config/users.d.xml`
+        // (with `extract: false` it would be `config/<hash>.zip` instead).
+        const usersConfigXml = generateUsersConfigXml({
+            schemaAdmin,
+            profiles,
+            vpcCidr: vpc.vpcCidrBlock
+        });
+        const usersConfigDeployment = new BucketDeployment(this, "ClickHouseUsersConfigDeployment", {
+            sources: [Source.data("users.d.xml", usersConfigXml)],
+            destinationBucket: backupBucket,
+            destinationKeyPrefix: "config",
+            prune: false,
+            retainOnDelete: true
+        });
+        const amiHardwareType = inferAmiHardwareType(instanceType);
+        const dataAz = Stack.of(this).availabilityZones[0];
+        const clickHouseHost = this.getHostEndpoint();
+        const backupDestUrl = `https://${backupBucket.bucketName}.s3.${Stack.of(this).region}.amazonaws.com/backup/`;
+        const optimiseQuery = [
+            ...REPLACING_MERGE_TREE_TABLES.map((table) => `OPTIMIZE TABLE ${CLICKHOUSE_DATABASE_NAME}.${table} FINAL`),
+            ...OPTIMISE_MV_TABLES.map((table) => `OPTIMIZE TABLE ${CLICKHOUSE_DATABASE_NAME}.${table}`)
+        ].join("; ");
+        const adminSecret = expectDefined(userSecrets.get(schemaAdmin.name), `schemaAdmin '${schemaAdmin.name}' secret not minted.`);
+        const scheduledTasks = [];
+        if (optimiseEnabled) {
+            scheduledTasks.push({
+                name: "ClickHouseOptimiseTask",
+                schedule: optimiseSchedule,
+                image: ContainerImage.fromRegistry(CLICKHOUSE_IMAGE),
+                cpu: OPTIMISE_TASK_CPU_UNITS,
+                memoryLimitMiB: OPTIMISE_TASK_MEMORY_MIB,
+                command: [
+                    "clickhouse-client",
+                    "--host",
+                    clickHouseHost,
+                    "--port",
+                    String(CLICKHOUSE_NATIVE_PORT),
+                    "--user",
+                    schemaAdmin.name,
+                    "--query",
+                    `${optimiseQuery};`
+                ],
+                secrets: {
+                    CLICKHOUSE_PASSWORD: EcsSecret.fromSecretsManager(adminSecret.secret, "password")
+                },
+                logRetention: RetentionDays.ONE_WEEK,
+                securityGroups: [securityGroup]
+            });
+        }
+        if (backupEnabled && backupTaskLogGroup !== undefined) {
+            scheduledTasks.push({
+                name: "ClickHouseBackupTask",
+                schedule: backupSchedule,
+                image: ContainerImage.fromRegistry(CLICKHOUSE_IMAGE),
+                cpu: BACKUP_TASK_CPU_UNITS,
+                memoryLimitMiB: BACKUP_TASK_MEMORY_MIB,
+                command: [
+                    "sh",
+                    "-c",
+                    // Password via CLICKHOUSE_PASSWORD env, not --password on argv (argv → /proc/<pid>/cmdline).
+                    `STAMP=$(date +%Y%m%d-%H%M%S) && clickhouse-client --host ${clickHouseHost} --port ${CLICKHOUSE_NATIVE_PORT} --user ${schemaAdmin.name} --query "BACKUP DATABASE ${CLICKHOUSE_DATABASE_NAME} TO S3('${backupDestUrl}weekly-$STAMP/')"`
+                ],
+                secrets: {
+                    CLICKHOUSE_PASSWORD: EcsSecret.fromSecretsManager(adminSecret.secret, "password")
+                },
+                logGroup: backupTaskLogGroup,
+                securityGroups: [securityGroup]
+            });
+        }
+        const clickHouseContainerSecrets = {};
+        for (const name of allUserNames) {
+            const userSecret = expectDefined(userSecrets.get(name), `user '${name}' secret not minted.`);
+            clickHouseContainerSecrets[userPasswordEnvName(name)] =
+                userSecret.getImport("password");
+        }
+        const ecsCompute = new EcsCompute(this, "Compute", {
+            type: "ecs",
+            vpc,
+            cluster: {
+                loadBalancer: false,
+                securityGroup,
+                scheduledTasks
+            },
+            services: [
+                {
+                    name: "ClickHouseService",
+                    capacityProvider: "EC2",
+                    desiredCount,
+                    serviceDiscovery: {
+                        name: CLICKHOUSE_CLOUDMAP_SERVICE_NAME,
+                        // getaddrinfo clients require A; AWS rejects A under HOST/BRIDGE → AWS_VPC.
+                        dnsRecordType: "A"
+                    },
+                    networkMode: NetworkMode.AWS_VPC,
+                    // Omit → CDK auto-creates a service SG that no consumer ingress targets.
+                    securityGroups: [securityGroup],
+                    deployment: { minHealthyPercent: 0, maxHealthyPercent: 100 },
+                    ec2Config: {
+                        instanceType,
+                        machineImage: EcsOptimizedImage.amazonLinux2023(amiHardwareType),
+                        instanceMonitoring: Monitoring.BASIC,
+                        availabilityZones: [dataAz],
+                        persistentDataVolume: {
+                            sizeGb: CLICKHOUSE_EBS_VOLUME_SIZE_GB,
+                            deviceName: CLICKHOUSE_EBS_DEVICE_NAME,
+                            availabilityZone: dataAz,
+                            iops: CLICKHOUSE_EBS_IOPS,
+                            throughputMbps: CLICKHOUSE_EBS_THROUGHPUT_MBPS
+                        },
+                        userData,
+                        desiredCapacity: 1,
+                        minCapacity: 1,
+                        maxCapacity: 1,
+                        memoryLimitMiB: CLICKHOUSE_TASK_MEMORY_MIB,
+                        tags: {
+                            [CLICKHOUSE_SERVER_ROLE_TAG.key]: CLICKHOUSE_SERVER_ROLE_TAG.value
+                        }
+                    },
+                    containers: [
+                        {
+                            name: CLICKHOUSE_SERVER_CONTAINER_NAME,
+                            image: CLICKHOUSE_IMAGE,
+                            stopTimeout: CLICKHOUSE_STOP_TIMEOUT_SECONDS,
+                            entryPoint: ["/bin/bash", "-c"],
+                            command: [buildClickHouseEntrypointWrapper()],
+                            secretsImport: clickHouseContainerSecrets,
+                            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
+                                }
+                            ],
+                            volumes: [
+                                {
+                                    name: "clickhouse-data",
+                                    hostSourcePath: CLICKHOUSE_DATA_MOUNT_PATH,
+                                    mountPath: "/var/lib/clickhouse"
+                                },
+                                {
+                                    name: "clickhouse-config",
+                                    hostSourcePath: `${CLICKHOUSE_DATA_MOUNT_PATH}/${CLICKHOUSE_CONFIG_SUBDIR}`,
+                                    mountPath: "/etc/clickhouse-server/config.d",
+                                    readOnly: true
+                                },
+                                {
+                                    name: "clickhouse-users",
+                                    hostSourcePath: `${CLICKHOUSE_DATA_MOUNT_PATH}/${CLICKHOUSE_USERS_SUBDIR}`,
+                                    mountPath: "/etc/clickhouse-server/users.d",
+                                    readOnly: true
+                                }
+                            ],
+                            healthCheck: {
+                                command: [
+                                    "CMD-SHELL",
+                                    `wget -q -O /dev/null http://127.0.0.1:${CLICKHOUSE_HTTP_PORT}/ping || exit 1`
+                                ],
+                                interval: CLICKHOUSE_HEALTH_CHECK.INTERVAL_SECONDS,
+                                timeout: CLICKHOUSE_HEALTH_CHECK.TIMEOUT_SECONDS,
+                                retries: CLICKHOUSE_HEALTH_CHECK.RETRIES,
+                                startPeriod: CLICKHOUSE_HEALTH_CHECK.START_PERIOD_SECONDS
+                            }
+                        }
+                    ]
+                }
+            ]
+        });
+        const clickHouseTaskDef = ecsCompute.getTaskDefinition("ClickHouseService");
+        if (!clickHouseTaskDef) {
+            throw new Error("ClickHouseDatabase: EcsCompute did not expose a ClickHouseService task definition — expected the service to be registered.");
+        }
+        backupBucket.grantReadWrite(clickHouseTaskDef.taskRole);
+        coldTierBucket?.grantReadWrite(clickHouseTaskDef.taskRole);
+        const instanceRole = ecsCompute.getInstanceRole();
+        if (instanceRole === undefined) {
+            throw new Error("ClickHouseDatabase: EcsCompute did not expose an instance role — expected an EC2-backed capacity provider.");
+        }
+        instanceRole.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName("AmazonSSMManagedInstanceCore"));
+        backupBucket.grantRead(instanceRole, "config/*");
+        adminSecret.secret.grantRead(instanceRole);
+        const adminSecretName = clickHouseUserSecretName(schemaAdmin.name);
+        // Password via CLICKHOUSE_CLIENT_PASSWORD env, not --password on argv
+        // (argv → /proc/<pid>/cmdline). `jq -r .password` on an empty pipeline
+        // emits literal "null" exit 0 — `pipefail` + null/empty guard close
+        // the silent-auth-fail trap. Validate password BEFORE the atomic mv
+        // so a fetch failure leaves the OLD on-disk users.d intact.
+        const reloadScript = [
+            `set -euo pipefail`,
+            `aws s3 cp "s3://${backupBucket.bucketName}/config/users.d.xml" /var/lib/clickhouse/users.d/fjall.xml.new`,
+            `CONTAINER=$(docker ps -q --filter "label=com.amazonaws.ecs.container-name=${CLICKHOUSE_SERVER_CONTAINER_NAME}" | head -n1)`,
+            `if [ -z "$CONTAINER" ]; then mv /var/lib/clickhouse/users.d/fjall.xml.new /var/lib/clickhouse/users.d/fjall.xml; echo "fjall:reload:status=skipped reason=no-container" >&2; exit 0; fi`,
+            `ADMIN_PASSWORD=$(aws secretsmanager get-secret-value --secret-id "${adminSecretName}" --query SecretString --output text | jq -r .password)`,
+            `if [ -z "$ADMIN_PASSWORD" ] || [ "$ADMIN_PASSWORD" = "null" ]; then echo "fjall:reload:status=failed reason=password-fetch" >&2; exit 1; fi`,
+            `mv /var/lib/clickhouse/users.d/fjall.xml.new /var/lib/clickhouse/users.d/fjall.xml`,
+            `docker exec -i -e CLICKHOUSE_CLIENT_PASSWORD="$ADMIN_PASSWORD" "$CONTAINER" clickhouse-client --port 9000 --user ${schemaAdmin.name} -q "SYSTEM RELOAD USERS"`
+        ].join("\n");
+        const region = Stack.of(this).region;
+        const account = Stack.of(this).account;
+        const reloadParameters = {
+            DocumentName: "AWS-RunShellScript",
+            Targets: [
+                {
+                    Key: `tag:${CLICKHOUSE_SERVER_ROLE_TAG.key}`,
+                    Values: [CLICKHOUSE_SERVER_ROLE_TAG.value]
+                }
+            ],
+            Parameters: { commands: [reloadScript] },
+            CloudWatchOutputConfig: { CloudWatchOutputEnabled: false }
+        };
+        const reloadPhysicalResourceId = PhysicalResourceId.of(`${usersConfigDeployment.deployedBucket.bucketName}/${Fn.select(0, usersConfigDeployment.objectKeys)}`);
+        const reloadCustomResource = new AwsCustomResource(this, "ClickHouseUsersReload", {
+            onCreate: {
+                service: "SSM",
+                action: "sendCommand",
+                parameters: reloadParameters,
+                physicalResourceId: reloadPhysicalResourceId,
+                ignoreErrorCodesMatching: "InvalidInstanceId|InvocationDoesNotExist"
+            },
+            onUpdate: {
+                service: "SSM",
+                action: "sendCommand",
+                parameters: reloadParameters,
+                physicalResourceId: reloadPhysicalResourceId,
+                ignoreErrorCodesMatching: "InvalidInstanceId|InvocationDoesNotExist"
+            },
+            policy: AwsCustomResourcePolicy.fromStatements([
+                new PolicyStatement({
+                    actions: ["ssm:SendCommand"],
+                    resources: [`arn:aws:ssm:${region}::document/AWS-RunShellScript`]
+                }),
+                // Keep this statement separate — merging into the document statement
+                // would drop the tag condition (IAM conditions are per-statement).
+                new PolicyStatement({
+                    actions: ["ssm:SendCommand"],
+                    resources: [`arn:aws:ec2:${region}:${account}:instance/*`],
+                    conditions: {
+                        StringEquals: {
+                            [`aws:ResourceTag/${CLICKHOUSE_SERVER_ROLE_TAG.key}`]: CLICKHOUSE_SERVER_ROLE_TAG.value
+                        }
+                    }
+                })
+            ])
+        });
+        reloadCustomResource.node.addDependency(usersConfigDeployment);
+        this.connections = new Connections({
+            securityGroups: [securityGroup],
+            defaultPort: Port.tcp(CLICKHOUSE_HTTP_PORT)
+        });
+        const declareOutput = (name, value) => {
+            const output = new CfnOutput(this, name, { value });
+            output.overrideLogicalId(name);
+        };
+        declareOutput("Endpoint", clickHouseHost);
+        declareOutput("HttpPort", String(CLICKHOUSE_HTTP_PORT));
+        declareOutput("NativePort", String(CLICKHOUSE_NATIVE_PORT));
+        declareOutput("DatabaseName", CLICKHOUSE_DATABASE_NAME);
+        for (const [name, secret] of userSecrets) {
+            declareOutput(`${toPascalCase(name)}SecretArn`, secret.secret.secretArn);
+        }
+        declareOutput("BackupBucketName", backupBucket.bucketName);
+        if (coldTierBucket !== undefined) {
+            declareOutput("ColdTierBucketName", coldTierBucket.bucketName);
+        }
+    }
+    /**
+     * Returns the Fjall `Secret` wrapper for the named user. Throws with a
+     * `Known users:` list if the name is not present in the construct's
+     * `schemaAdmin:` / `managedPasswords:` props.
+     */
+    getUser(name) {
+        const secret = this.#users.get(name);
+        if (secret === undefined) {
+            throw new Error(`ClickHouseDatabase: unknown user '${name}'. ` +
+                `Known users: ${Array.from(this.#users.keys()).join(", ")}`);
+        }
+        return secret;
+    }
+    /**
+     * Non-throwing sibling of `getUser`. Returns the Fjall `Secret` wrapper for
+     * the named user, or `undefined` when no such user is declared. Used by
+     * `getMigrationContributions()` to gracefully skip credential wiring when the
+     * caller did not declare a `migrationUser:` on the database.
+     */
+    tryGetUser(name) {
+        return this.#users.get(name);
+    }
+    getHttpPort() {
+        return CLICKHOUSE_HTTP_PORT;
+    }
+    getNativePort() {
+        return CLICKHOUSE_NATIVE_PORT;
+    }
+    getHostEndpoint() {
+        return `${CLICKHOUSE_CLOUDMAP_SERVICE_NAME}.${App.getInstance().getNamespace().namespaceName}`;
+    }
+    getHttpUrl() {
+        return `http://${this.getHostEndpoint()}:${this.getHttpPort()}`;
+    }
+    getNativeUrl() {
+        return `tcp://${this.getHostEndpoint()}:${this.getNativePort()}`;
+    }
+    getDatabaseName() {
+        return CLICKHOUSE_DATABASE_NAME;
+    }
+    getBackupBucket() {
+        return this.#backupBucket;
+    }
+    getColdTierBucket() {
+        return this.#coldTierBucket;
+    }
+    grantConnect(grantee) {
+        this.connections.allowDefaultPortFrom(grantee);
+        this.connections.allowFrom(grantee, Port.tcp(CLICKHOUSE_NATIVE_PORT));
+    }
+    /**
+     * Migration contributions for a task connecting to this ClickHouse cluster
+     * via `service.connections:`. Contributes env (`CLICKHOUSE_URL`,
+     * `CLICKHOUSE_DATABASE`, plus the managed-user manifest under
+     * `CLICKHOUSE_MANAGED_USERS`) and egress to the cluster's HTTP port.
+     *
+     * **Schema admin.** The bootstrap-privileged user's password is imported as
+     * `SCHEMA_ADMIN_PASSWORD` so customer SQL migrations can authenticate. The
+     * schema admin is defined in `users.d/fjall.xml` (users_xml storage =
+     * read-only); its password syncs via XML reload on EC2 boot or via the
+     * Custom::AWS SYSTEM RELOAD USERS resource on stack updates — NOT via the
+     * migration helper. The admin is therefore NOT included in the manifest.
+     *
+     * **Managed-password workload users.** Every entry in `managedPasswords` is
+     * added to the manifest (name only — profile binding is customer SQL's
+     * concern) AND its `password` secret is imported as `USER_<NAME>_PASSWORD`
+     * so the migration container boots with each plaintext already in
+     * `process.env`. The helper reads the env vars directly — no runtime
+     * `secretsmanager:GetSecretValue` SDK call is needed; ECS executionRole
+     * carries the IAM grant via the standard `secretsImport` framework path.
+     */
+    getMigrationContributions() {
+        const environment = {
+            CLICKHOUSE_URL: this.getHttpUrl(),
+            CLICKHOUSE_DATABASE: this.getDatabaseName()
+        };
+        const secretsImport = {};
+        const adminSecret = this.getUser(this.#schemaAdmin.name);
+        secretsImport.SCHEMA_ADMIN_PASSWORD = adminSecret.getImport("password");
+        for (const name of this.#managedPasswordNames) {
+            const userSecret = this.getUser(name);
+            secretsImport[userPasswordEnvName(name)] =
+                userSecret.getImport("password");
+        }
+        environment[CLICKHOUSE_MANAGED_USERS_ENV] = JSON.stringify([
+            ...this.#managedPasswordNames
+        ]);
+        const primarySg = this.connections.securityGroups[0];
+        const egress = [];
+        if (primarySg !== undefined) {
+            egress.push({
+                peer: primarySg,
+                port: Port.tcp(this.getHttpPort()),
+                description: "Migration runner to ClickHouse HTTP for DDL apply"
+            });
+        }
+        else {
+            Annotations.of(this).addWarning("ClickHouseDatabase: no primary security group exposed; migration " +
+                "runner egress not auto-wired. Provide egress manually in " +
+                "separateTaskDef if needed.");
+        }
+        return { environment, secretsImport, egress };
+    }
+    /**
+     * Wires a task definition to connect to ClickHouse as `opts.user` (if
+     * supplied). Adds `CLICKHOUSE_URL` / `CLICKHOUSE_DATABASE` env vars to the
+     * task's default container; when `opts.user` is set, also adds
+     * `CLICKHOUSE_USER` (plain env) and `CLICKHOUSE_PASSWORD` (Secrets
+     * Manager-backed env var resolved from the user's secret). Throws if the
+     * user is unknown. Callers separately call `grantConnect(service)` on the
+     * resulting ECS service for the network grant — `TaskDefinition` itself
+     * isn't `IConnectable`.
+     */
+    connectFromTask(task, opts) {
+        const container = task.defaultContainer;
+        if (container === undefined) {
+            throw new Error("ClickHouseDatabase.connectFromTask: task has no default container");
+        }
+        container.addEnvironment("CLICKHOUSE_URL", this.getHttpUrl());
+        container.addEnvironment("CLICKHOUSE_DATABASE", CLICKHOUSE_DATABASE_NAME);
+        if (opts?.user !== undefined) {
+            const userSecret = this.getUser(opts.user);
+            container.addEnvironment("CLICKHOUSE_USER", opts.user);
+            container.addSecret("CLICKHOUSE_PASSWORD", EcsSecret.fromSecretsManager(userSecret.secret, "password"));
+        }
+    }
+}

package/dist/lib/patterns/aws/compute.d.ts

@@ -1,12 +1,12 @@
 import { Runtime } from "aws-cdk-lib/aws-lambda";
 import { type Construct } from "constructs";
-import { type IEcsCompute, type ILambdaCompute, type IEc2Compute, type AnyCompute, isCompute, isEcsCompute, isLambdaCompute, isEc2Compute } from "./interfaces/compute.js";
+import { type ComputeType, type IEcsCompute, type ILambdaCompute, type IEc2Compute, type AnyCompute, isCompute, isEcsCompute, isLambdaCompute, isEc2Compute } from "./interfaces/compute.js";
 import type App from "../../app.js";
-import { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, type ResolvedScalingConfig, resolveScalingConfig } from "./computeEcs.js";
+import { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, type ContainerDependency, type EcsMigrationsConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig } from "./computeEcs.js";
 import { LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions } from "./computeLambda.js";
 import { Ec2Compute, type Ec2ComputeProps, type SshConfig } from "./computeEc2.js";
-export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps, type SshConfig };
-export type ComputeType = "ecs" | "ec2" | "lambda";
+export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, type ContainerDependency, type EcsMigrationsConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps, type SshConfig };
+export type { ComputeType } from "./interfaces/compute.js";
 /**
  * Configuration defaults for each compute type.
  */
@@ -33,9 +33,7 @@ export declare const COMPUTE_DEFAULTS: {
         readonly MAX_CAPACITY: 1;
     };
     readonly ECS: {
-        /** AWS sample image used when no ECR repository is provided */
         readonly FALLBACK_IMAGE: "amazon/amazon-ecs-sample";
-        /** Default tag for ECR images */
         readonly IMAGE_TAG: "latest";
     };
     readonly LAMBDA: {