MySQL Orchestrator: A Complete Guide for SREs and DBAs

Introduction:

High availability and replication topologies are critical for any production-grade MySQL environment. Orchestrator is an open-source tool created by GitHub to manage, visualize, and automate MySQL replication. For SREs and DBAs, understanding and deploying Orchestrator is essential to ensure seamless failover, topology recovery, and monitoring.

This guide provides a complete step-by-step tutorial—from installation to Prometheus/Grafana monitoring integration—along with best practices and troubleshooting tips.

What is Orchestrator?

Orchestrator is a MySQL replication topology manager and visualizer. Its main functions are:

• Detects and visualizes replication topologies automatically.
• Automates failover and recovery.
• Supports complex replication setups: GTID, binlog servers, multi-source replication.
• Provides a web UI for interactive topology management.
• Includes a rich HTTP API for automation.

Orchestrator Functionality:

• MySQL Nodes → Orchestrator queries replication status.
• Orchestrator Service → Maintains a backend database (SQLite/MySQL/PostgreSQL).
• Web UI & API → Provides visualization and management.
• Integration → Exports metrics to Prometheus (via an exporter) for monitoring.

Installing Orchestrator:

Installation Steps:

sudo apt update
sudo apt install wget curl unzip -y

# Download latest orchestrator binary
wget https://github.com/openark/orchestrator/releases/download/v3.2.6/orchestrator_3.2.6_amd64.deb

# Install
sudo dpkg -i orchestrator_3.2.6_amd64.deb
sudo apt-get install -f -y

# Verify
/usr/local/orchestrator/orchestrator --version

# Add to path
echo 'export PATH=$PATH:/usr/local/orchestrator' >> ~/.bashrc
source ~/.bashrc
orchestrator --version

Configure Orchestrator:

sudo nano /etc/orchestrator.conf.json

Add/Update this in the conf file as shown below:

{
  "Debug": true,
  "ListenAddress": ":3002",
  "BackendDB": "sqlite",
  "SQLite3DataFile": "/var/lib/orchestrator/orchestrator.sqlite3",
  "PrometheusStatus": true,
  "MySQLTopologyUser": "orchestrator",
  "MySQLTopologyPassword": "your password"
}

Fix SQLite Permissions:

sudo mkdir -p /var/lib/orchestrator
sudo touch /var/lib/orchestrator/orchestrator.sqlite3
sudo chown $(whoami):$(whoami) /var/lib/orchestrator/orchestrator.sqlite3
sudo chmod 664 /var/lib/orchestrator/orchestrator.sqlite3

Verify Orchestrator:

orchestrator -c discover -i 127.0.0.1:3306

Build Lightweight Exporter:

We used a Python script (instead of compiling Percona’s exporter)

sudo nano /opt/orchestrator_exporter.py

#!/usr/bin/env python3
from http.server import BaseHTTPRequestHandler, HTTPServer
import requests

EXPORTER_PORT = 9202
ORC_API = "http://localhost:3002/api/status"

class MetricsHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/metrics":
            try:
                r = requests.get(ORC_API)
                healthy = 1 if r.json().get("Details", {}).get("Healthy") else 0
                metrics = f"orchestrator_healthy {healthy}\n"
            except Exception:
                metrics = "orchestrator_healthy 0\n"
            self.send_response(200)
            self.end_headers()
            self.wfile.write(metrics.encode("utf-8"))
        else:
            self.send_response(404)
            self.end_headers()

if __name__ == "__main__":
    print(f"Orchestrator exporter running on port {EXPORTER_PORT}")
    HTTPServer(("0.0.0.0", EXPORTER_PORT), MetricsHandler).serve_forever()

Run and Test this Script:

python3 /opt/orchestrator_exporter.py

curl http://localhost:9202/metrics

It will Returns:

orchestrator_healthy 1

Make Exporter Persistent:

Create service:

sudo nano /etc/systemd/system/orchestrator_exporter.service

[Unit]
Description=Orchestrator Prometheus Exporter
After=network.target

[Service]
ExecStart=/usr/bin/python3 /opt/orchestrator_exporter.py
Restart=always
User=systemuser

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl daemon-reexec
sudo systemctl enable orchestrator_exporter
sudo systemctl start orchestrator_exporter
sudo systemctl status orchestrator_exporter

Once Orchestrator is installed successfully we can able to view the UI as shown in the below image.

Add to Prometheus:

sudo nano /etc/prometheus/prometheus.yml

scrape_configs:
  - job_name: "orchestrator_exporter"
    static_configs:
      - targets: ["localhost:9202"]

Restart Prometheus:

sudo systemctl restart prometheus

Prometheus exporter shows orchestrator_exporter status is UP/DOWN:

Create Grafana Dashboard:

In Grafana Add Prometheus data source as

http://localhost:9090

Click New dashboard and in the PromQL query box select the metrics orchestrator_healthy as shown in the image, then save the dashboard as Orchestrator.

Once the dashboard saved successfully, we can monitor the Orchestrator dashboard whenever we need.

Visualization:

Statistics shows 1 (healthy) or 0 (unhealthy).

Conclusion:

We have now:

• Installed Orchestrator
• Built a custom Prometheus exporter
• Integrated it into Prometheus + Grafana

This setup is modular we can add more API calls in the Python exporter to capture:

• Failover counts
• Cluster size
• Node states

Orchestrator simplifies MySQL replication management and, combined with Prometheus + Grafana, gives a robust observability stack. Following the exact steps above ensures a production-ready setup for any SRE/DBA team.