MariaDB MaxScale 운영 정리 — 자동 failover와 읽기/쓰기 분리

MaxScale은 MariaDB 앞에 두는 DB 프록시다. 읽기/쓰기 분리, 자동 failover, 커넥션 풀링을 담당한다. 운영하면서 정리해 둔 설정과 명령을 한 번에 모았다.

Note

아래 설정의 IP·계정·비밀번호는 전부 예시 플레이스홀더다. 실제 운영에선 maxpasswd로 암호화한 값이나 별도 secrets 관리를 쓰고, 설정 파일에 평문 비밀번호를 두지 않는다.

핵심 구성 (maxscale.cnf)

크게 server → monitor → service → listener 네 블록으로 이해하면 된다.

[maxscale]
threads=auto
logdir=/var/log/maxscale
datadir=/var/lib/maxscale

# --- 백엔드 DB 노드 ---
[server1]
type=server
address=10.0.0.11
port=3306
protocol=MariaDBBackend
proxy_protocol=on          # 클라이언트 실 IP 전달 (아래 참고)

[server2]
type=server
address=10.0.0.12
port=3306
protocol=MariaDBBackend
proxy_protocol=on

# --- 클러스터 모니터 (자동 failover의 핵심) ---
[cluster-monitor]
type=monitor
module=mariadbmon
servers=server1,server2
user=maxscale
password=********
monitor_interval=800ms
replication_user=repl
replication_password=********
auto_rejoin=true           # 복구된 옛 마스터를 슬레이브로 자동 재편입
auto_failover=true         # 마스터 다운 시 슬레이브 자동 승격
failcount=5
failover_timeout=60s
switchover_timeout=90s
verify_master_failure=true

# --- 읽기/쓰기 분리 서비스 ---
[rw-service]
type=service
router=readwritesplit
servers=server1,server2
user=maxscale
password=********
max_slave_connections=100%
max_slave_replication_lag=1   # 지연 1초 넘는 슬레이브는 읽기에서 제외
master_accept_reads=true

# --- 클라이언트 접속 지점 ---
[rw-listener]
type=listener
service=rw-service
protocol=MariaDBClient
port=3306
address=0.0.0.0

readwritesplit 라우터가 쓰기는 마스터로, 읽기는 슬레이브로 자동 분배한다. max_slave_replication_lag으로 지연이 큰 슬레이브를 읽기 풀에서 빼는 게 실무에서 중요하다.

자동 failover / switchover

mariadbmon이 auto_failover=true면 마스터 장애 시 슬레이브를 자동 승격한다. 계획된 전환(switchover)은 수동으로 명령한다.

# server2를 새 마스터로, server1을 슬레이브로 전환
maxctrl call command mariadbmon switchover cluster-monitor server2 server1

# 상태 확인
maxctrl list servers
maxctrl show monitor cluster-monitor

Tip

auto_rejoin=true면 죽었다 살아난 옛 마스터가 자동으로 새 마스터의 슬레이브로 재편입된다. 스플릿브레인을 막으려면 verify_master_failure와 failcount를 환경에 맞게 조정한다.

maxctrl 운영 명령

과거 maxadmin은 maxctrl로 대체됐다(MaxScale 2.3+).

maxctrl list servers                      # 서버/상태/복제 지연 한눈에
maxctrl list services
maxctrl show service rw-service
maxctrl set server server1 maintenance    # 점검 모드 (읽기 풀에서 제외)
maxctrl clear server server1 maintenance
maxctrl list sessions                      # 현재 커넥션

클라이언트 IP 보존 (proxy protocol)

MaxScale을 거치면 DB 입장에서 접속 IP가 전부 MaxScale의 IP로 보인다. 그러면 user@host 권한도, 감사 로그도 무의미해진다. proxy protocol을 켜면 실제 클라이언트 IP가 DB까지 전달된다.

# 1) MaxScale — server 섹션 (재기동 필요)
proxy_protocol=on

# 2) MariaDB — my.cnf (dynamic, 재기동 불필요)
proxy_protocol_networks = 10.0.0.0/24

proxy_protocol_networks는 동적 변수라 DB 재기동 없이 적용된다. 다만 MaxScale 쪽은 재기동이 필요해 서비스 중단 창이 필요하다.

자주 만난 에러

Connection killed by MaxScale: Router could not recover from connection errors.

MaxScale에서 proxy_protocol=on을 켰는데 MariaDB에 proxy_protocol_networks가 설정되지 않았을 때 발생한다. DB의 my.cnf(또는 동적 변경)에 접속 대역을 추가하면 해결된다.

-- 동적으로 즉시 적용
SET GLOBAL proxy_protocol_networks = '10.0.0.0/24';

정리

구성은 server → monitor(mariadbmon) → service(readwritesplit) → listener 순으로 이해
읽기 품질은 max_slave_replication_lag으로 지킨다
계획 전환은 maxctrl ... switchover, 장애는 auto_failover가 처리
proxy protocol 미설정이 “Router could not recover” 에러의 단골 원인
설정 파일에 평문 비밀번호를 두지 말 것 (maxpasswd / secrets)