provision-tenant
Skill1 starsChanged 5 months agoApache-2.0View on GitHub
Provision a new tenant (one virtual ArcadeDB database) by driving the control-plane provisioning Step Functions flow. Use when onboarding a tenant or re-running a partially-failed provision (the flow is idempotent).
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- control-plane/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- helm/CLAUDE.mdCLAUDE.md
- terraform/CLAUDE.mdCLAUDE.md
- add-cellSkill
- cell-capacity-reportSkill
- deprovision-tenantSkill
- dr-drillSkill
- incident-triageSkill
- migrate-schemaSkill
- new-adrSkill
- restore-tenantSkill
- retire-cellSkill
- review-terraform-planSkill
- rotate-secretsSkill
- security-baseline-checkSkill
- tenant-erasureSkill
- tenant-usage-reportSkill
- upgrade-arcadedbSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
No click-ops (PD #6): never CREATE DATABASE / CREATE USER by hand against a node.
- Very specific: line 46
Pick the cell (placement): Run cell-capacity-report for home_geo + env + tier.
- Distinctive: line 67
Run the flow twice with the same input and confirm the second run is a clean no-op (idempotency), then verify each artifact exists exactly …
- Distinctive: line 75
Residency: all of the above live only in the home geo's account/region.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Provision a tenant
Onboards one tenant = one virtual ArcadeDB database in its home geo, with a least-priv user, HNSW + Lucene indexes, KMS-backed secret, a backup policy, and an
activeregistry record. Phase note: the provisioning flow and its Lambda targets are an INTERFACE STUB until Phase 2; executing it against AWS MUTATES the cluster + control plane and is out of scope until after CTO sign-off and the Phase-2 control-plane rollout. Dry-run / read-only inspection is fine now.
Prerequisites
- The tenant's
home_geomatches the control plane you are operating (EU operators run the EU control plane; US operators run the US control plane). There is no cross-geo provisioning — see Safety checks. - AWS access to the correct geo's account (
ACCOUNT_ID, region per geo) via SSO; permission to start thekb-provision-tenantstate machine and read DynamoDB / Secrets Manager. - Phase 2 deployed: provisioning state machine + its Lambdas wired (currently stubs). If you are pre-Phase-2, you may only validate inputs and read the registry.
- A target cell exists in-geo for this
env/tierwith free capacity (confirm withcell-capacity-report). If none has room, runadd-cellfirst — do not pack a full cell. - The artifact under change:
statemachine.asl.json; registry contract:schema.ts.
Inputs
| Input | Type | Notes |
tenant_id | string | Stable unique id; becomes the registry PK and seeds db_name. |
home_geo | eu | us | Immutable residency anchor. Must equal the control plane's geo. |
tier | standard | enterprise | Drives placement, durability (tx_wal_flush), backup cadence. |
projected_size_gb | number | Placement signal. > ~50 GB (or enterprise) → dedicated cell, never pooled. |
env | dev | stage | prod | Selects the cell pool; prod cells are 3-node/quorum. |
The state machine reads $.control_plane_geo (injected by the runner) and compares it to $.home_geo.
Safety checks (MUST pass before proceeding)
- Residency (PD #1):
home_geo == control_plane_geo. If not, STOP — the flow's first stateAssertHomeGeowillFailwithResidencyViolationand there must be no EU↔US data path. Never "fix" this by running the other geo's control plane against this tenant. Registry is regional DynamoDB, never a global table (ADR-0008). - No root creds (ArcadeDB gotcha): provisioning creates a per-DB least-priv user + group, never root. The root password is SET-ONCE and is not what tenants use. Do not pass or reuse root.
- Placement isolation (PD #3, sizing):
projected_size_gb > ~50ortier == enterprise⇒ a dedicated cell (cell_isolation: cluster). A DB cannot be split across nodes; you scale by adding cells, not by overloading one. Never place a big/enterprise tenant in a pooled namespace cell. - Capacity (no per-DB quotas): ArcadeDB has no per-DB resource quotas — the control plane caps capacity. Confirm the target cell is not
full(any cap trips:max_standard_dbs ~150,max_page_ram_commit_ratio ~0.60,max_disk_used_ratio ~0.70). Over-packing risks OOM-kill and quorum loss (PD #7). - Encryption (PD #5): the engine provides none. The secret lands in Secrets Manager under KMS; the DB's EBS/snapshots are KMS-encrypted. Do not write creds anywhere else (no plaintext, no ticket, no chat).
- No click-ops (PD #6): never
CREATE DATABASE/CREATE USERby hand against a node. Provisioning is only via the Step Functions flow so it stays idempotent + audited. The cell itself was created by Terraform/Helm/GitOps. - No public DB (PD #4): you provision through the control plane / VPC-internal path only; ports 2480/2424/2434/5432/6379/7687 are never reachable publicly.
- Approval gate: running the flow against AWS is a mutating, post-sign-off action. Get the documented approval before
start-execution.
Steps
The flow is idempotent — every state is a no-op if its effect already exists, so a re-run safely resumes a partial provision. Order is fixed by
statemachine.asl.json.
- Gather + validate inputs. Confirm
tenant_id,home_geo,tier,projected_size_gb,env. Re-checkhome_geoequals your control-plane geo (Safety check #1). - Pick the cell (placement). Run
cell-capacity-reportforhome_geo + env + tier. Apply the placement rule: enterprise or> ~50 GB⇒ dedicated cell; otherwise least-loaded pooled cell with headroom. If none qualifies, runadd-cellbefore continuing. Record the chosencell_id. - [APPROVAL GATE — AWS-mutating, post-sign-off] Obtain the documented approval to provision into the live geo account.
- Start the provisioning execution with the validated payload (geo account, correct region). Example (placeholders — do not run pre-approval):
The flow then executes, in order:aws stepfunctions start-execution \ --state-machine-arn arn:aws:states:REGION:ACCOUNT_ID:stateMachine:kb-provision-tenant \ --name "provision-${tenant_id}-$(date +%s)" \ --input '{"tenant_id":"<id>","home_geo":"<eu|us>","tier":"<standard|enterprise>","projected_size_gb":<n>,"env":"<dev|stage|prod>","cell_id":"<from step 2>"}'AssertHomeGeo— residency guard;Fails on cross-geo (PD #1).CreateDatabase— creates the tenant DB replicated 3x on the chosen cell (no-op if it exists).CreateLeastPrivUser— per-DB least-priv user + group, not root (set-once-root gotcha; least-privilege).CreateIndexes— HNSW (vector) + Lucene (full-text) for GraphRAG (ADR-0024).StoreCredentials— DB creds into Secrets Manager, KMS-encrypted, rotatable (ADR-0018).RegisterBackup— backup schedule + retention tier (ADR-0015). Note: backups are hot per-DB ZIPs that exclude WAL, with no incremental / no PITR — EBS snapshots (ADR-0016) supplement.UpdateRegistry— set registrystatus=activeand emit an audit event (the app-layer substitute for native audit, which ArcadeDB lacks).
- Watch the execution to
Succeed. On any task failure it routes toProvisioningFailed(emits a failure audit event + marks the registry); fix the cause and re-run the same input — idempotency converges.
Verification
Run the flow twice with the same input and confirm the second run is a clean no-op (idempotency), then verify each artifact exists exactly once:
- DB: the tenant DB exists on
cell_id, replicated across the 3 cell nodes (one per AZ in prod). Writes go to the leader, reads fan to replicas. - User: the per-DB least-priv user + group exist; root was not used.
- Indexes: HNSW and Lucene indexes are present on the DB.
- Secret: a Secrets Manager secret holds the DB creds (KMS-encrypted);
secret_arn_pointerin the registry resolves to it. - Backup: a
backup_policyis registered with the expected cadence/retention for the tier. - Registry + audit:
TenantRecord.status == activewith correcthome_geo,cell_id,db_name; acreate-dbAuditEvent(outcome: success) was emitted in the correct geo (ADR-0008). - Residency: all of the above live only in the home geo's account/region; nothing replicated cross-geo.
Rollback / if it goes wrong
- Cross-geo rejection (
ResidencyViolation): expected and correct — do not bypass. Provision from the matching geo's control plane. - Partial failure: the flow is idempotent and self-healing — re-run the same input to resume from where it stopped. Do not hand-patch resources.
- Wrong placement (e.g. a big/enterprise tenant landed in a pooled cell, or cell now over cap): do not drop the DB manually. Run
deprovision-tenantto cleanly remove it (drops DB, revokes secret, emits deletion evidence), confirm withcell-capacity-report/add-cell, then re-provision with corrected placement. - Secret created but DB failed (or vice-versa): re-run; idempotency reconciles. Never leave an orphan secret —
deprovision-tenantrevokes it if you must back out fully. - Note: restore/recovery for an existing tenant is a different runbook (
restore-tenant); restoring requires the target DB to not exist — never restore over a live tenant DB.
Related
- ADR-0008 — tenant registry: regional DynamoDB, never global table (adr).
- ADR-0007 (residency SCP), ADR-0018 (secrets/ESO), ADR-0015 (backup), ADR-0016 (snapshots), ADR-0024 (GraphRAG indexes), ADR-0004 (cell isolation).
- State machine:
provisioning/statemachine.asl.json; registry contract:registry/schema.ts. - Skills:
deprovision-tenant,cell-capacity-report,add-cell,restore-tenant,rotate-secrets. - Architecture:
docs/architecture.md; assumptions:docs/assumptions.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

