Fjall Infrastructure

Published fjall infrastructure components and utilities.

Upgrade notes

21.0.0 — ClickHouse identities by workload class (breaking)

ClickHouseDatabase no longer shares one schemaAdmin principal across the migration task, the schema gate and the maintenance sidecars. Each workload class now authenticates as its own identity, so no two classes contend for the same max_concurrent_queries_for_user cap:

| identity | holder | | ------------------------- | ----------------------------- | | schemaAdmin.name (XML) | migration task ONLY | | fjall_schema_gate (SQL) | materialised gate container | | fjall_maintenance (SQL) | OPTIMIZE FINAL + BACKUP tasks |

What changes in a synthesised stack:

• App containers lose SCHEMA_ADMIN_USER / SCHEMA_ADMIN_PASSWORD. They keep EXPECTED_CH_SCHEMA_VERSION. A container image that runs its own in-process ClickHouse schema check reading those two variables must drop it — the materialised gate container performs the check.
• The gate container authenticates as fjall_schema_gate via FJALL_SCHEMA_GATE_CH_USER / FJALL_SCHEMA_GATE_CH_PASSWORD (read-only, SELECT on <db>._schema_migrations only).
• The OPTIMIZE and BACKUP scheduled tasks authenticate as fjall_maintenance. Their execution roles read that identity's secret, not the schema admin's. Both scripts open with a migrate ↔ maintenance activity pre-flight and log fjall:maintenance:status=<ok|deferred|failed> markers; status=failed pages via a new ClickHouseMaintenanceFailedAlarm.
• Two new fixed-name Secrets Manager secrets — fjall/clickhouse/fjall-schema-gate-password and fjall/clickhouse/fjall-maintenance-password — are minted by the construct. They are NOT injected into the ClickHouse service container, so the ClickHouse service task definition is unchanged by the upgrade.
• The fjall_ user-name prefix is reserved. A schemaAdmin.name or managedPasswords entry starting with fjall_ fails synth.

Deploy order: the identities are SQL-provisioned by the migration runner (@fjall/clickhouse 21 — bump the migration image before this construct), so the migration task must run once under 21.x BEFORE anything authenticates as the new identities. Deploy the Database stack, then the Compute stack that carries the migration task, and only then let the schedules fire.

Rollback: rolling back to 20.x deletes the two framework secrets, which Secrets Manager only schedules (30-day recovery window). Re-adopting 21.x inside that window fails on the held names — first run aws secretsmanager restore-secret --secret-id fjall/clickhouse/<name>-password or aws secretsmanager delete-secret --secret-id … --force-delete-without-recovery for each of the two secrets.

Useful commands

• npm run build — clean, bundle the Lambda assets and compile TypeScript to dist/
• npm run watch — recompile on change
• npm test — run the Vitest suites
• npm run typecheck — type-check the library

Synthesis and deployment go through the fjall CLI (fjall deploy), which assembles the stacks from an application's fjall/ directory. The package is not deployed with cdk deploy on its own.

Using the constructs

The constructs are consumed through the fjall CLI: fjall create app and fjall add <resource> write the infrastructure.ts that composes them, and fjall deploy synthesises and deploys it. Every construct is also exported from the package root for direct use; the reference lives at docs.fjall.io.

Licence

Proprietary — see LICENSE.