Provisioning technical design
How Simulacro turns a topology into running MariaDB nodes — current state and the planned real backend.
Current phase
Alpha. Provisioning runs through a real executor port with a mock backend — the full async lifecycle, run records, and access flow are exercised end to end, but no real cloud resources are created yet. Hosts and credentials shown in access instructions are synthetic until a real backend is wired in.
Shared control plane
- Web (Next.js): operator UI, create wizard, live provisioning progress, inline access instructions.
- API (NestJS): validation and role-based access, the lifecycle state machine, preset catalog, and an immutable audit timeline plus provisioning-run records.
- Persistence: SQLite for environments, events, provisioning runs, and extension requests; a JSON store for the preset catalog.
- Lifecycle states: REQUESTED → PROVISIONING → READY, with STOPPED (pause/resume), DECOMMISSIONING → DELETED, and FAILED. Provision and decommission run asynchronously; each is a persisted, retryable run.
Executor port and backends
The control plane never talks to infrastructure directly. Every lifecycle operation goes through one injectable executor port, selected at runtime by MSRS_EXECUTOR. Swapping backends never changes the control plane, its contracts, or persisted state.
Mock backend — active
Creates no infrastructure. Synthesizes structurally-real per-node outputs (hosts, IPs, SSH user), simulates latency, and can simulate failure so the FAILED path is testable. Used to prove the lifecycle, run records, and UI.
Terraform + Ansible — planned
Terraform/OpenTofu provisions the cloud infrastructure (network, security, compute, storage). Ansible installs the exact MariaDB/MaxScale versions and wires the topology (replication, Galera bootstrap, MaxScale). Target substrate: cloud VMs (AWS/GCP).
Target provisioning approach
- Deliver one golden-path topology first — one async primary with N replicas — then broaden to Galera and dual-Galera-via-async.
- Deterministic MariaDB install: pinned versions from the official CS/ES repositories against a supported OS × version matrix, failing fast on unsupported tuples.
- Shareable SSH access via short-lived, CA-signed certificates and a jump host, with a generated ssh_config fragment and per-node aliases.
VM is the default profile; Docker and Kubernetes are targeted profiles for container/cluster-specific reproductions.
Diagrams
