Search

Self managed - DDL/DML Endpoint

문서번호 : 11-3671425

Document Information

•
최초 작성일 : 2025.09.11
•
최종 수정일 : 2025.10.30
•
이 문서는 아래 버전을 기준으로 작성되었습니다.
◦
SingleStoreDB : 8.9.25
◦
SingleStore Client : 1.0.7
◦
Python : 3.6.8

Goal

Self-managed 환경에서 DDL / DML endpoint 를 구현하기 위해, Load Balancer 의 Aggregator health check 요청에 응답하는 HTTP 서버를 구현한다.
HTTP 서버는 Load Balancer 에 의해 연결되는 모든 Aggregator 노드의 서버에서 실행하며, 시스템 서비스로 등록하여 서버 crash 후 재부팅 시에도 자동으로 재시작되도록 한다.
사용자가 설정한 주기마다 Aggregator 의 Health 체크 결과(/agg_check)와 MA 노드 여부(/mk_check)를 확인하여 결과를 반환한다.
본 문서에서는 각 서버에 하나의 Aggregator 노드만 구성된 클러스터 환경을 기준으로 Checker 서비스를 구현함.

Solution

HTTP 서버는 각 URL 에 체크 결과를 반환하고, Load Balancer 를 사용하여 endpoint 구성 시 health check 를 위한 URL 을 세팅한다.
•
(optional) DDL Endpoint (/ma_check)
◦
DML Endpoint 의 조건을 모두 만족
◦
현재 Aggregator 의 id 와 MA 노드 id 가 동일한지 확인
→ 위 조건을 모두 만족할 때 DDL 실행 가능한 Aggregator 노드로 판단
•
DML Endpoint (/agg_check)
◦
노드에 정상 접속 여부 확인
◦
online 상태의 MA 노드가 연결된 클러스터인지 확인
◦
모든 master partition 이 online 상태인지 확인
◦
consensus_enabled= on 인 경우, demoted 된 클러스터에 속하지 않았는지 확인
→ 위 조건을 모두 만족할 때 DML 실행 가능한 Aggregator 노드로 판단

HTTP 서버 실행 및 테스트

Load Balancer 에 구성된 모든 Aggregator 노드 서버에 코드 파일을 배포한 뒤, 올바른 결과가 반환되는지 테스트한다.
agg_health_v1.0.3.py
11.6 KiB
•
DDL Enpoint (MA_CHECK_YN="Y”일 때만 동작)
◦
조건을 모두 만족하는 경우 /ma_check 로 HTTP 200 을 반환한다.
◦
조건을 하나라도 만족하지 못하는 경우 /ma_check 로 HTTP 503을 반환한다.
•
DML Enpoint
◦
조건을 모두 만족하는 경우 /agg_check 로 HTTP 200을 반환한다.
◦
조건을 하나라도 만족하지 못하는 경우 /agg_check 로 HTTP 503을 반환한다.
환경 변수 설정
Variable Name
Desc.
MA_CHECK_YN
MA Check 실행 여부 (Y/N, default: Y)
HEALTH_CHECK_PORT
health check 결과를 반환할 HTTP port (default: 3309)
CHECK_INTERVAL
check 주기 (sec, default: 20)
QUERY_TIMEOUT
최대 쿼리 실행 시간 (sec, default: 10)
DB Connection 과 관련된 환경변수는 .env 파일을 사용하여 별도 관리
(O/S 권한 700(.ap), 600(.env) 부여하여 파일 접근 관리)
$ ls -al ~/.ap total 8 drwx------. 2 opc opc 18 Oct 27 08:24 . drwx------. 9 opc opc 4096 Oct 27 08:58 .. -rw-------. 1 opc opc 65 Oct 27 08:24 .env $ cat ~/.ap/.env DB_HOST=localhost DB_PORT=3306 DB_USER=root DB_PASS=sdbadmin123!
SQL
복사
실행 로그 예시
# Only health check # healthy $ python /singlestore_work/agg_health.py [2025-09-11 08:25:20] [INFO] Aggregator Health Check Server running on port 3309 [2025-09-11 08:25:20] [INFO] HealthCheck: Healthy, LastError: [2025-09-11 08:25:31] [INFO] HealthCheck: Healthy, LastError: [2025-09-11 08:25:41] [INFO] HealthCheck: Healthy, LastError: ... # unhealthy [2025-09-11 08:27:55] [INFO] HealthCheck: Unhealthy, LastError: Step 1: Aggregator connection check Failed [2025-09-11 08:28:05] [INFO] HealthCheck: Unhealthy, LastError: Step 1: Aggregator connection check Failed # health check + MA check # MA, healthy [2025-09-23 07:14:43] [INFO] Aggregator Health Check Server running on port 3309 [2025-09-23 07:14:43] [INFO] HealthCheck: Healthy [2025-09-23 07:14:43] [INFO] MA Check: This node is MA [2025-09-23 07:14:53] [INFO] HealthCheck: Healthy [2025-09-23 07:14:54] [INFO] MA Check: This node is MA # MA, unhealthy # unhealthy 일 때 /ma_check 도 503 반환, 별도로 로깅되지는 않음. [2025-09-23 07:15:04] [ERROR] HealthCheck: Unhealthy, LastError: Step 1: Aggregator connection check Failed [2025-09-23 07:15:14] [ERROR] HealthCheck: Unhealthy, LastError: Step 1: Aggregator connection check Failed # CA, healthy [2025-09-23 07:14:45] [INFO] Aggregator Health Check Server running on port 3309 [2025-09-23 07:14:45] [INFO] HealthCheck: Healthy [2025-09-23 07:14:45] [INFO] MA Check: This node is not MA [2025-09-23 07:14:55] [INFO] HealthCheck: Healthy [2025-09-23 07:14:55] [INFO] MA Check: This node is not MA # CA, unhealthy # 쿼리 실패 시 QUERY_TIMEOUT + CHECK_INTERVAL 주기로 check 결과 반환됨. [2025-09-23 07:15:35] [ERROR] HealthCheck: Unhealthy, LastError: Step 4: information_schema is not selectable [2025-09-23 07:16:16] [ERROR] HealthCheck: Unhealthy, LastError: Step 4: information_schema is not selectable
SQL
복사

서비스 호출

외부 서버에서 직접 서비스 호출

# 1) MA # DDL Endpoint (MA check) -> 200 반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.36:3309/ma_check 200 # DML Endpoint (healthy check) -> 200 반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.36:3309/agg_check 200 # 2) CA # DDL Endpoint (MA check) -> 503 반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.104:3309/ma_check 503 # DML Endpoint (healthy check) -> 200 반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.104:3309/agg_check 200 # MA 노드 stop 후 확인 # 3) MA # DDL Endpoint (MA check) -> 503 반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.36:3309/ma_check 503 # DML Endpoint (healthy check) -> 503반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.36:3309/agg_check 503 # 4) CA # DDL Endpoint (MA check) -> 503 반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.104:3309/ma_check 503 # DML Endpoint (healthy check) -> 503반환 $ curl -s -o /dev/null -w "%{http_code}\n" http://10.0.0.104:3309/agg_check 503
SQL
복사

Load Balancer 로 endpoint 구성

•
DDL Endpoint 구성 예시
◦
Health check 정책 추가
health check 정책 설정 시 Health-check HTTP port(3309) 와 url path(/ma_check) 을 입력한다.
OCI Load Balancer 의 health check 정책 구성 예시
◦
Health check 모니터링
MA 노드(10.0.0.36) 만 healthy 상태로, 나머지 Aggregator 노드는 unhealty 상태로 확인된다.
OCI Load Balancer 의 health check 결과 모니터링 예시
◦
DDL Endpoint 의 listener port (tcp) 로 쿼리 실행 (n회 반복 실행)
MA 노드(10.0.0.36)에만 연결되는 것을 확인할 수 있다.
$ singlestore -s -h10.0.0.246 -P3306 -psdbadmin123! -e "show aggregators; select aggregator_id();" singlestore-client: [Warning] Using a password on the command line interface can be insecure. Host Port State Opened_Connections Average_Roundtrip_Latency_ms Master_Aggregator NodeId Availability_Group 10.0.0.104 3306 offline 0 NULL 0 1 NULL 10.0.0.36 3306 online 2 NULL 1 7 NULL 10.0.0.143 3306 online 2 0.000 0 11 NULL aggregator_id() 7
Shell
복사
•
DML Endpoint 구성 예시
◦
Health check 정책 추가
health check 정책 설정 시 Health-check HTTP port 와 url path 을 입력한다.
OCI Load Balancer 의 health check 정책 구성 예시
◦
Health check 모니터링
OCI Load Balancer 의 health check 결과 모니터링 예시 - 모든 노드 healthy 상태인 경우
OCI Load Balancer 의 health check 결과 모니터링 예시 - Aggregator(10.0.0.14) 노드 down 상태인 경우
◦
DML Endpoint 의 listener port (tcp) 로 쿼리 실행 (n회 반복 실행)
healthy 상태인 Aggregator 노드에만 연결되는 것을 확인할 수 있다.
$ singlestore -s -h10.0.0.91 -P3306 -psdbadmin123! -e "show aggregators; select aggregator_id();" singlestore-client: [Warning] Using a password on the command line interface can be insecure. Host Port State Opened_Connections Average_Roundtrip_Latency_ms Master_Aggregator NodeId Availability_Group 10.0.0.104 3306 offline 0 NULL 0 1 NULL 10.0.0.36 3306 online 2 NULL 1 7 NULL 10.0.0.143 3306 online 2 0.000 0 11 NULL aggregator_id() 7 $ singlestore -s -h10.0.0.91 -P3306 -psdbadmin123! -e "show aggregators; select aggregator_id();" singlestore-client: [Warning] Using a password on the command line interface can be insecure. Host Port State Opened_Connections Average_Roundtrip_Latency_ms Master_Aggregator NodeId Availability_Group 10.0.0.104 3306 offline 0 NULL 0 1 NULL 10.0.0.36 3306 online 2 0.000 1 7 NULL 10.0.0.143 3306 online 1 NULL 0 11 NULL aggregator_id() 11
Shell
복사

서비스 등록

서비스 파일을 생성하여 서버가 재부팅 되었을 때도 자동으로 재 시작 되도록 한다.
$ cat /etc/systemd/system/agg-health.service [Unit] Description=SingleStore Aggregator node Health Check HTTP Server After=network.target [Service] ExecStart=/usr/bin/python3 /singlestore_work/agg_health.py WorkingDirectory=/singlestore_work Restart=always RestartSec=5 User=1001 # 서비스 실행할 O/S user id 로 변경 [Install] WantedBy=multi-user.target # 서비스 실행 $ sudo systemctl daemon-reload $ sudo systemctl start agg-health.service # 서비스 자동 재시작 설정 $ sudo systemctl enable agg-health.service Created symlink /etc/systemd/system/multi-user.target.wants/agg-health.service → /etc/systemd/system/agg-health.service. # 서비스 상태 체크 $ systemctl status agg-health.service ● agg-health.service - SingleStore Aggregator node Health Check HTTP Server Loaded: loaded (/etc/systemd/system/agg-health.service; enabled; vendor preset: disabled) Active: active (running) since Mon 2025-10-27 06:46:37 GMT; 30s ago Main PID: 23676 (python3) Tasks: 4 (limit: 48316) Memory: 11.2M CGroup: /system.slice/agg-health.service └─23676 /usr/bin/python3 /singlestore_work/agg_health.py
Bash
복사

References

History

일자
작성자
비고
2025.08.25.
mk.kang
최초 작성
2025.09.23.
mk.kang
코드 수정
2025.10.27.
mk.kang
코드 , 서비스 세팅 방법 수정
2025.10.30.
mk.kang
코드 수정