문서번호 : 11-3671425

Document Information

• 최초 작성일 : 2025.09.11
• 최종 수정일 : 2025.12.05
• 이 문서는 아래 버전을 기준으로 작성되었습니다.
  • 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)를 확인하여 결과를 반환한다.

<aside> 💡

본 문서에서는 각 서버에 하나의 Aggregator 노드만 구성된 클러스터 환경을 기준으로 Checker 서비스를 구현함.

</aside>

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.4.py

• DDL Enpoint (MA_CHECK_YN="Y”일 때만 동작)
  • 조건을 모두 만족하는 경우 /ma_check 로 HTTP 200 을 반환한다.
  • 조건을 하나라도 만족하지 못하는 경우 /ma_check 로 HTTP 503을 반환한다.
• DML Enpoint
  • 조건을 모두 만족하는 경우 /agg_check 로 HTTP 200을 반환한다.
  • 조건을 하나라도 만족하지 못하는 경우 /agg_check 로 HTTP 503을 반환한다.

환경 변수 설정