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 keepEXPECTED_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_gateviaFJALL_SCHEMA_GATE_CH_USER/FJALL_SCHEMA_GATE_CH_PASSWORD(read-only,SELECTon<db>._schema_migrationsonly). - 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 logfjall:maintenance:status=<ok|deferred|failed>markers;status=failedpages via a newClickHouseMaintenanceFailedAlarm. - Two new fixed-name Secrets Manager secrets —
fjall/clickhouse/fjall-schema-gate-passwordandfjall/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. AschemaAdmin.nameormanagedPasswordsentry starting withfjall_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 todist/npm run watch— recompile on changenpm test— run the Vitest suitesnpm 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.