erawan-cluster | Database Cluster Automation API

async cluster lifecycle + live proxy config

erawan-cluster is a Go API that drives Ansible-based database cluster provisioning for MySQL InnoDB Cluster, PostgreSQL Patroni with etcd, and optional HAProxy tenant config generation.

View API Payloads Read Runtime Requirements

Build

Go + Chi

Lean REST API surface with strict JSON validation and job state persistence.

Automation

Ansible

Cluster rollout, service bootstrap, verification, and job resume flows.

Topologies

1-N Nodes

Single-node bootstrap or full primary plus replicas depending on the stack.

System View

Control plane + cluster workers

v1.02

API Host

Go + Ansible

Serves REST endpoints, writes job state, runs Ansible playbooks, and pushes HAProxy updates.

MySQL Path

InnoDB Cluster + MySQL Shell, optional Router bootstrap, resume and rollback support.

PostgreSQL Path

Patroni + etcd bootstrap with leader election, replica bring-up, and verification.

Important current behavior

MySQL now manages cluster-admin credentials internally and expects local root socket access on target nodes.
PostgreSQL now internally generates and persists cluster passwords for deploy and resume flows.
HAProxy remains optional and is configured as a separate tenant-aware feature set.

Requirements

Everything the base environment needs before deployment

This section consolidates the current repo requirements from the API host, MySQL, and PostgreSQL docs into one operational checklist.

API Host

Control

Go 1.22+
ansible-playbook installed
SSH client with key-based access to all target DB nodes
HAProxy installed if proxy features are enabled
sudo permission for HAProxy reload command

MySQL Nodes

InnoDB

MySQL installed and running
mysqlsh installed
Local MySQL administration as OS root through a Unix socket
Optional mysqlrouter if Router bootstrap is enabled
Single-node or primary-plus-secondary topology support
Node-to-node MySQL connectivity on port 3306 or the chosen MySQL port

PostgreSQL Nodes

Patroni

PostgreSQL installed on every node
patroni[etcd] installed
etcd installed
Single-node or primary-plus-standby topology support
Ports 2379, 2380, 5432, and 8008 reachable
Fresh-cluster bootstrap behavior resets etcd and PostgreSQL data directories once per job

Deployment Model

Job-based orchestration with resumable steps

Every cluster rollout is broken into tagged Ansible steps. That gives the API enough structure to track progress, resume from failure points, and keep the deployment shape predictable.

MySQL

Preflight, instance preparation, cluster creation, optional add-instance, optional Router bootstrap, verify, and optional app DB init.

PostgreSQL

Preflight, base config, primary and standby config, cluster bootstrap, verification, and optional app DB init.

MySQL Flow

1. Preflight validates MySQL, MySQL Shell, Router prerequisites, and connectivity.
2. Instances are prepared for InnoDB Cluster and cluster-admin access is normalized.
3. The primary creates or recovers the cluster.
4. Secondary nodes join with clone-based recovery.
5. Router is optionally bootstrapped and verified on all DB nodes.

PostgreSQL Flow

1. Patroni and etcd prerequisites are discovered on every node.
2. Base config installs service units and shared runtime files.
3. Primary and standby Patroni configs are rendered with internal credentials.
4. etcd starts first, then Patroni boots the primary and replicas.
5. Verification checks REST membership and replication state.

Credential Handling

Reduced caller secret surface

stored privately per job

MySQL

Cluster-admin credentials (admin_user / admin_password) are generated internally and returned in the deploy 202 response under secret. They are also available via Get Job and Resume responses, and reused automatically on resume. Use these credentials — not the app user — for the metrics endpoint.

PostgreSQL

Superuser, replication, and admin passwords are generated internally if not supplied. All three are returned in the deploy 202 response under secret and reused automatically on resume. Use postgres_user and postgres_password from the deploy response to call the metrics endpoint.

Endpoints

Primary API surface

System

GET /health
GET /docs

HAProxy

POST   /haproxy/config/mysql
POST   /haproxy/config/pgsql
DELETE /haproxy/config
GET    /haproxy/configs
GET    /haproxy/configs/download
POST   /haproxy/reload

MySQL Cluster

POST /cluster/mysql/deploy
POST /cluster/mysql/metrics
GET  /cluster/mysql/jobs
GET  /cluster/mysql/jobs/{jobID}
POST /cluster/mysql/jobs/{jobID}/resume
POST /cluster/mysql/jobs/{jobID}/rollback

PostgreSQL Cluster

POST /cluster/pgsql/deploy
POST /cluster/pgsql/metrics
GET  /cluster/pgsql/jobs
GET  /cluster/pgsql/jobs/{jobID}
POST /cluster/pgsql/jobs/{jobID}/resume

Payloads

Copy-ready examples for the current API contract

MySQL Deploy

Current examples reflect the reduced external credential requirements.

JSON

{
  "cluster_name": "prodCluster",
  "primary_ip": "192.168.122.154",
  "standby_ips": ["192.168.122.111"],
  "new_user": "appuser",
  "new_user_password": "AppUser#2026",
  "new_user_ssl_required": true,
  "new_db": "appdb",
  "assume_prepared": false,
  "bootstrap_router": true,
  "ssh_port": 22,
  "mysql_port": 3306,
  "mysql_version": 8,
  "step_timeout_seconds": 900
}

{
  "cluster_name": "postgres-cluster",
  "primary_ip": "10.0.0.1",
  "standby_ips": ["10.0.0.2", "10.0.0.3"],
  "new_user": "appuser",
  "new_user_password": "AppUser#2026",
  "new_user_ssl_required": true,
  "new_db": "appdb",
  "ssh_port": 22,
  "postgres_port": 5432,
  "postgres_version": 16,
  "step_timeout_seconds": 900
}

// POST /haproxy/config/mysql
{
  "port": 25010,
  "node_ips": ["10.10.107.182", "10.10.107.183"],
  "db_port": 6446
}

// POST /haproxy/config/pgsql
{
  "port": 25432,
  "node_ips": ["10.0.0.1", "10.0.0.2"],
  "db_port": 5432,
  "patroni_port": 8008
}

// POST /cluster/mysql/metrics
// host: omit — server reads PROXY_HOST env (127.0.0.1)
// user: admin_user from deploy response
{
  "port": 25010,
  "user": "clusteradmin",
  "password": "<admin_password from deploy response>",
  "ssl_mode": "disable",
  "connect_timeout": 10,
  "categories": [],
  "databases": [],
  "limit": 20
}

// MySQL categories (7): cluster | uptime | connections
// replication | performance | query | maintenance
// Response always includes database_count (all user DBs)
// databases: [] = all; ["appdb","mydb"] = filter per-DB fields

// POST /cluster/pgsql/metrics
// host: omit — server reads PROXY_HOST env (127.0.0.1)
// user: postgres_user from deploy response
// node_ips: required for cluster + failover categories
{
  "port": 25005,
  "node_ips": [
    "10.0.0.1",
    "10.0.0.2",
    "10.0.0.3"
  ],
  "user": "postgres",
  "password": "<postgres_password from deploy response>",
  "ssl_mode": "require",
  "connect_timeout": 10,
  "patroni_port": 8008,
  "categories": [],
  "databases": [],
  "limit": 20
}

// PostgreSQL categories (8): cluster | uptime | failover
// connections | replication | performance | query | maintenance
// Response always includes database_count (non-template DBs)
// databases: [] = all; ["appdb"] = filter per-DB fields

Resume Payload

{
  "new_user_password": "AppUser#2026"
}

MySQL Rollback

{}

Behavior Notes

Use standby_ips: [] for single-node bootstrap.
Set bootstrap_router: false to skip MySQL Router.
Set assume_prepared: true only when MySQL nodes were prepared earlier.
SSH credentials are configured on the API host via env vars — they are not part of any request payload.
Omit PostgreSQL cluster passwords to use auto-generated values returned in the deploy response and reused on resume.
Set postgres_version to target a specific major version (14–18). Defaults to 16.
Metrics host is optional — the server reads PROXY_HOST env when omitted. Set port to the HAProxy listen port.
For PostgreSQL metrics, supply node_ips to enable Patroni leader auto-discovery for the cluster and failover categories.
Every metrics response includes database_count — total user databases on the server.
databases: [] returns all databases. Pass names to filter per-database fields (connections by_database, slow queries, fragmented tables, autovacuum workers).
by_database shows all user databases including those with zero active connections.
categories: [] collects all categories. Pass a subset to reduce response size and collection time.

Developer

Contact the developer behind this project

Repository ownership and project contact are linked here so the landing page also works as a simple handoff point for collaborators, reviewers, and future maintenance.

Name

Nann Visal

Maintainer and developer contact for the erawan-cluster repository.

Repository

github.com/Nann-Visal/erawan-cluster

Use the repository page for project source, issue tracking, and direct maintainer context.

Open GitHub Repository Contact Developer Profile