MySQL Router Deployment Guide

This article explains how to use innodb_cluster_router.yml to deploy MySQL Router on top of an existing InnoDB Cluster. The default is single-node App mode; enable keepalived HA mode explicitly when a VIP is required.

1. Scope

The upstream Cluster has already been deployed by innodb_cluster.yml
Single-node App mode is the default
Two-node keepalived HA mode is supported
The Router REST API is enabled by default so mysqlrouter_exporter can be added later

2. Dependency chain

Item	Details
Prerequisites	`dbbotctl env setup` is complete, `innodb_cluster.yml` has already succeeded, the `[dbbot_router]` inventory is ready, and Router nodes can reach the Cluster nodes
Required variables	`router_bootstrap_server`, `mysql_cluster_admin_user` / `mysql_cluster_admin_password`, and `mysql_router_user` / `mysql_router_password`
HA variables	HA mode also requires `router_enable_ha: true`, `router_vip`, `router_net_work_interface`, and `router_ha_nodes`
Conditional variables	When `router_rest_api_auth_mode: file`, also set `router_rest_api_file_user` / `router_rest_api_file_password`; if you change the REST API port, update `router_ports.http.port` at the same time
Next step	If Router metrics are required, continue with `router_exporter_install.yml`, then register the targets in Prometheus with `dbbotctl exporter register -t router`

3. Inventory

App mode can use a single Router node:

[dbbot_router]
192.0.2.151 ansible_user=root ansible_ssh_pass="'<your_password>'"

HA mode usually uses two Router nodes:

[dbbot_router]
192.0.2.151 ansible_user=root ansible_ssh_pass="'<your_password>'"
192.0.2.152 ansible_user=root ansible_ssh_pass="'<your_password>'"

The IPs above use RFC 5737 documentation ranges and are examples only. Replace them with your actual host addresses.

4. Key variables

Edit mysql_ansible/playbooks/vars/var_innodb_cluster_router.yml. Default App mode:

router_enable_ha: false
router_bootstrap_server: 192.0.2.131

mysql_cluster_admin_user: clusteradmin
mysql_cluster_admin_password: "Dbbot_clusteradmin@8888"
mysql_router_user: mysqlrouter
mysql_router_password: "Dbbot_mysqlrouter@8888"

router_rest_api_auth_mode: file
router_rest_api_file_user: router_api_user
router_rest_api_file_password: "Dbbot_router_api_user@8888"

To enable HA, also configure:

router_enable_ha: true
router_vip: 192.0.2.150
router_net_work_interface: ens33
router_ha_nodes:
  - ip: 192.0.2.151
    role: MASTER
    priority: 100
  - ip: 192.0.2.152
    role: BACKUP
    priority: 90

Notes:

router_bootstrap_server must be a reachable node in the current Cluster.
mysql_cluster_admin_* is used by mysqlrouter --bootstrap.
mysql_router_* is the account used by Router to read Cluster metadata.
router_rest_api_file_* only applies when router_rest_api_auth_mode: file; the later mysqlrouter_exporter flow reuses these credentials by default.
router_net_work_interface must be the real interface name on the Router nodes. Before using HA mode, confirm it with ip route or ip addr. Sample environments using the dbbot 192.168.161.* test inventory usually use enp1s0; do not copy ens33 blindly.

5. Execute deployment

App mode:

cd /usr/local/dbbot/mysql_ansible/playbooks
ansible-playbook innodb_cluster_router.yml

If HA mode is not persisted in the variables file, pass it temporarily:

cd /usr/local/dbbot/mysql_ansible/playbooks
ansible-playbook innodb_cluster_router.yml -e router_enable_ha=true

During execution, enter confirm as prompted.

6. Post-deployment validation

Common checks:

systemctl status mysqlrouter
In HA mode, also check systemctl status keepalived
ss -lntp | egrep '6446|6447|8443'

App mode connection example:

mysql -h 192.0.2.151 -P 6446 -u<user> -p

HA mode connection example:

mysql -h 192.0.2.150 -P 6446 -u<user> -p

<user> must be an application or test account whose MySQL grants match the source observed by the backend MySQL instance. admin@127.0.0.1 is suitable for direct local MySQL instance checks, such as connecting to instance port 3307; when connecting to Router port 6446, backend authentication matches the Router-to-MySQL connection source, so do not assume it is the same as 127.0.0.1 in the client command.

7. Uninstall Router

The Router uninstall entry stops MySQL Router and removes its systemd unit, symlink, installation directory, configuration directory, data directory, and log directory:

cd /usr/local/dbbot/mysql_ansible/playbooks
ansible-playbook router_unsafe_uninstall.yml

To clean keepalived service state and Router HA scripts from an HA deployment, keep router_enable_ha: true in the variables file or pass:

ansible-playbook router_unsafe_uninstall.yml -e router_uninstall_remove_keepalived=true

During execution, enter confirm as prompted. By default, the playbook does not uninstall the keepalived RPM and does not remove the mysqlrouter Linux user. Set router_uninstall_remove_keepalived_package=true or router_uninstall_remove_user=true only when that is intended.

8. Next step

If you want to connect Router metrics to Prometheus, continue with: mysqlrouter_exporter and Router Registration.