3. aku#

개요#

aku(Altibase Kubernetes Utility)는 쿠버네티스의 스테이트풀셋(Statefulset)에서 스케일링(scaling)할 때 파드(Pod)의 시작 및 종료에 따라 Altibase의 데이터를 동기화하거나 동기화 정보를 초기화하는 등의 작업을 수행할 수 있게 도와주는 유틸리티이다. 즉, aku는 파드들간의 데이터 이중화를 도와주는 유틸리티로, Altibase의 데이터 스케일아웃(scale-out) 기능은 지원하지 않는다.

스테이트풀셋은 데이터베이스처럼 상태 유지가 필요한 애플리케이션을 지원하기 위한 쿠버네티스의 워크로드 컨트롤러 중 하나이며, 스케일링은 파드를 생성하거나 종료하는 것을 의미한다. 파드는 컨테이너들을 담고 있는 쿠버네티스의 리소스이며, 이 컨테이너에 Altibase 서버가 실행된다.

스테이트풀셋에서 스케일 업/다운할 때 아래의 조건에 해당하는 파드를 생성하거나 종료하고자 할 때 aku 유틸리티를 사용할 수 있다. 이때, aku 유틸리티가 Altibase 컨테이너에서 실행되도록 적당한 위치에 명령어를 추가해야 한다.

스케일 업#

기존 파드의 Altibase 서버와 동일한 데이터를 가진 파드를 생성한다.

가장 처음 생성된 파드를 aku에서는 마스터 파드(Master Pod)라고 부르며, 추가로 스케일 업하여 생성된 파드는 슬레이브 파드(Slave Pod)로 부른다.

스케일 다운#

파드를 종료할 때 Altibase 서버의 이중화 정보를 초기화한다.

구성 요소#

aku 유틸리티는 실행 파일과 설정 파일로 구성된다.

⚠️ 모든 파드에서 실행하는 aku 실행 파일은 같은 버전을 사용해야 하며, aku 설정 파일 내 프로퍼티도 같은 값을 가져야 한다. 일반적으로 aku 실행 파일과 aku 설정 파일은 Altibase 컨테이너 이미지에 포함되어 있다.

Altibase 서버와 aku는 같은 컨테이너에서 실행해야 한다.

aku 실행 파일#

실행 파일의 이름은 aku이며 $ALTIBASE_HOME/bin에 위치한다. aku를 실행하려면 먼저 환경변수 ALTIBASE_HOME을 설정해야 한다.

aku 설정 파일#

aku를 실행하면 aku 설정 파일을 가장 먼저 읽어 Altibase 데이터 동기화에 필요한 정보를 얻는다. aku 설정 파일의 이름은 aku.conf이며 $ALTIBASE_HOME/conf에 위치해야 한다. Altibase 패키지에 aku.conf.sample 이름의 예제 파일을 제공하므로, aku를 실행하기 전에 이 파일을 참고하여 aku.conf를 생성해야 한다. aku 설정 파일의 내용은 아래와 같다.

⚠️ '#' 다음에 오는 내용은 주석으로 처리한다.

# aku.conf.sample

#*****************************************************************
# Copyright 2022, Altibase Corporation or its subsidiaries.
# All rights reserved.
# Property File for Altibase AKU Utility
#*****************************************************************

#=================================================================
# Kubernetes setting Properties
#=================================================================
AKU_STS_NAME                  = altibase-sts    # statefulsets name
AKU_SVC_NAME                  = altibase-svc    # services name
AKU_SERVER_COUNT              = 4               # the number of Pods
#=================================================================
# Common Properties
#=================================================================
AKU_SYS_PASSWORD              = manager
AKU_PORT_NO                   = 20300
AKU_REPLICATION_PORT_NO       = 20301
AKU_QUERY_TIMEOUT             = 3600
AKU_QUERY_RETRY_COUNT         = 5
AKU_QUERY_RETRY_DELAY_MSEC    = 1000
#=================================================================
# aku start/end Properties
#=================================================================
AKU_ADDRESS_CHECK_COUNT       = 30
AKU_FLUSH_AT_START            = 1
AKU_FLUSH_TIMEOUT_AT_START    = 300
AKU_DELAY_START_COMPLETE_TIME = 0

AKU_FLUSH_AT_END              = 1
AKU_REPLICATION_RESET_AT_END  = 1
#=================================================================
# Replication Properties
#=================================================================
REPLICATIONS = (
    REPLICATION_NAME_PREFIX = AKU_REP
    SYNC_PARALLEL_COUNT     = 1
    (
        SYS.T1, SYS.T2 PARTITION P1,
        SYS.T3
    )
)

각 프로퍼티에 대해 살펴보자.

카테고리	프로퍼티 이름	기본값	설명
쿠버네티스 설정 프로퍼티	AKU_STS_NAME		쿠버네티스 오브젝트 명세에 정의한 스테이트풀셋 이름. 설정할 수 있는 값의 최대 길이는 63바이트이다.
	AKU_SVC_NAME		쿠버네티스 오브젝트 명세에 정의한 네트워크 서비스를 제공하는 서비스 이름. 설정할 수 있는 값의 최대 길이는 63바이트이다.
	AKU_SERVER_COUNT	4	aku 유틸리티로 동기화할 수 있는 Altibase 서버의 최대 개수. 쿠버네티스에서 스케일 업할 수 있는 파드 수를 의미하기도 한다. 설정할 수 있는 값의 범위는 1 ~ 6이다.
공통 프로퍼티	AKU_SYS_PASSWORD		데이터베이스 SYS 사용자 패스워드
	AKU_PORT_NO	20300	Altibase 서버의 서비스 포트. 설정할 수 있는 값의 범위는 1024 ~ 65535이다.
	AKU_REPLICATION_PORT_NO	20301	Altibase 이중화 포트. 설정할 수 있는 값의 범위는 1024 ~ 65535이다.
	AKU_QUERY_TIMEOUT	3600	Altibase 서버 프로퍼티 QUERY_TIMEOUT를 의미한다. aku에서 수행한 쿼리의 수행 시간이 이 값을 초과하면 해당 동작은 취소된다.
	AKU_QUERY_RETRY_COUNT	5	Altibase 서버에서 수행한 쿼리가 실패하면 이 값의 횟수만큼 재시도한다. 0이면 재시도하지 않는다.
	AKU_QUERY_RETRY_DELAY_MSEC	1000 (ms)	Altibase 서버에서 수행한 쿼리가 실패하면 이 값의 시간만큼 대기한 후 재시도한다. 0이면 대기하지 않고 재시도를 수행한다.
aku start/end 프로퍼티	AKU_ADDRESS_CHECK_COUNT	30	`aku -p start` 명령 수행 시 생성 중인 파드의 로컬 DNS가 엔드 포인트에 등록될 때까지 이 값의 횟수만큼 로컬 IP 접속을 시도한다.
	AKU_FLUSH_AT_START	1	`aku -p start` 명령 수행 시 이중화 갭을 제거할 것인지 설정한다. 1이면 FLUSH 명령으로 이중화 갭을 제거하고, 0이면 제거하지 않고 시작한다.
	AKU_FLUSH_TIMEOUT_AT_START	300	FLUSH WAIT 명령의 wait_time을 설정한다. 이 값이 0이면 FLUSH ALL을 수행하고 1 이상이면 FLUSH WAIT wait_time을 수행한다. 이 설정은 AKU_FLUSH_AT_START설정값이 1일 때만 유효하다.
	AKU_DELAY_START_COMPLETE_TIME	0(sec)	슬레이브 파드 생성 단계에서 내부적으로 데이터 동기화가 완료된 후 ADMIN_MODE 프로퍼티를 0으로 변경하기 전에 대기하는 시간을 설정한다.
	AKU_FLUSH_AT_END	1	슬레이브 파드에서 `aku -p end` 명령 수행 시 이중화 갭을 제거할 것인지 설정한다. 1이면 이중화 FLUSH ALL 명령으로 이중화 갭을 제거하고 0이면 제거하지 않는다.
	AKU_REPLICATION_RESET_AT_END	1	슬레이브 파드에서 `aku -p end` 명령 수행 시 RESET 명령으로 이중화 정보를 초기화할 것인지 설정한다. 1이면 이중화 정보를 초기화하며, 0이면 초기화하지 않는다.
이중화 프로퍼티	REPLICATIONS/REPLICATION_NAME_PREFIX		aku가 생성하는 Altibase 이중화 객체 이름의 접두사. 설정할 수 있는 값의 최대 길이는 37바이트이다. Altibase 이중화 객체 이름 생성 규칙을 참고한다.
	REPLICATIONS/SYNC_PARALLEL_COUNT	1	이중화 SYNC 수행 시 송신/수신 쓰레드의 수. 1부터 100까지 설정할 수 있다.

참고: Altibase 이중화 객체 이름 생성 규칙

aku에서 생성하는 Altibase 이중화 객체 이름 생성 규칙은 다음과 같다.

REPLICATION_NAME_PREFIX_[파드 번호][파드 번호]

REPLICATION_NAME_PREFIX
REPLICATIONS/REPLICATION_NAME_PREFIX 프로퍼티에서 설정한 문자열
파드 번호
쿠버네티스 스테이트풀셋이 생성하는 파드의 이름에서 pod_name_ 뒤에 위치한 숫자이며 각 파드들은 순차적으로 생성된 고유한 순번을 가진다. Altibase 이중화 객체 이름에는 이중화 쌍이 되는 두 파드 번호가 포함되며 작은 값이 앞에 위치한다.

예시: AKU_SERVER_COUNT = 4, REPLICATION_NAME_PREFIX = AKU_REP 로 설정된 경우 각 파드에서 생성되는 이중화 객체 이름

파드 번호	이중화 객체 이름	설명
pod_name-0	AKU_REP_01	pod_name-0과 pod_name-1의 이중화 객체
	AKU_REP_02	pod_name-0과 pod_name-2의 이중화 객체
	AKU_REP_03	pod_name-0과 pod_name-3의 이중화 객체
pod_name-1	AKU_REP_01	pod_name-0과 pod_name-1의 이중화 객체
	AKU_REP_12	pod_name-1과 pod_name-2의 이중화 객체
	AKU_REP_13	pod_name-1과 pod_name-3의 이중화 객체
pod_name-2	AKU_REP_02	pod_name-0과 pod_name-2의 이중화 객체
	AKU_REP_12	pod_name-1과 pod_name-2의 이중화 객체
	AKU_REP_23	pod_name-2와 pod_name-3의 이중화 객체
pod_name-3	AKU_REP_03	pod_name-0과 pod_name-3의 이중화 객체
	AKU_REP_13	pod_name-1과 pod_name-3의 이중화 객체
	AKU_REP_23	pod_name-2와 pod_name-3의 이중화 객체

⚠️ aku가 생성하는 Altibase 이중화 객체의 이름을 사용자가 임의로 생성,삭제 및 수정할 경우 비정상적인 결과가 발생할 수 있다.

Altibase 이중화 대상 설정#

사용자는 aku 설정 파일에서 aku가 생성한 Altibase 이중화 객체에서 관리할 테이블 또는 파티션을 지정할 수 있다. 이중화 대상을 지정하려면 이중화 관련 프로퍼티 설정 구문에 [사용자 이름].[테이블 이름] 또는 [사용자 이름].[테이블 이름] PARTITION [파티션 이름] 형식으로 이중화 대상의 정보를 추가해야 한다. 사용자 이름과 테이블 이름, 파티션 이름의 최대 길이는 모두 128바이트이다.

각 이중화 대상은 쉼표로 구분되며, 한 줄에 하나 이상의 이중화 대상을 입력할 수 있다.

다음은 T1~T9 테이블을 이중화 3개로 분리하여 관리하도록 설정하는 예시이다. T2 테이블의 경우, 파티션 P1 만 이중화 대상으로 설정하도록 했다.

#=================================================================
# Replication Properties
#=================================================================
REPLICATIONS = (
    REPLICATION_NAME_PREFIX = AKU_REP1
    SYNC_PARALLEL_COUNT     = 1
    (
        SYS.T1, SYS.T2 PARTITION P1,
        SYS.T3
    )
),
(
    REPLICATION_NAME_PREFIX = AKU_REP2
    SYNC_PARALLEL_COUNT     = 1
    (
        SYS.T4, SYS.T5, SYS.T6
    )
),
(
    REPLICATION_NAME_PREFIX = AKU_REP3
    SYNC_PARALLEL_COUNT     = 1
    (
        SYS.T7,
        SYS.T8,
        SYS.T9
    )
)

aku 사용하기#

구문#

aku
[-h]
[--help]
[-v]
[--version]
[-i]
[--info]
[-p [start | end | clean] ]
[--pod [start | end | clean] ]

파라미터#

-h, --help#

aku 유틸리티의 사용법을 출력한다.

-v, --version#

aku 유틸리티의 버전 정보를 출력한다. aku 유틸리티의 버전은 Altibase 서버와 같은 버전으로 사용하는 것을 권장한다.

-i, --info#

aku 설정 파일의 내용을 출력한다. 파일에 문법(syntax) 오류가 있는 경우 에러를 출력하며 정상적일 때 아래의 정보를 출력한다.

Altibase 서버 접속 정보(데이터베이스 사용자, 패스워드, Altibase 서비스 포트)
Altibase 이중화 포트
스케일 업 최대 수(최대 파드 수)
Altibase 이중화 객체 이름 및 이중화 대상 테이블 정보

-p, --pod [start | end | clean]#

스케일링으로 파드를 생성하거나 종료할 때 Altibase에서 수행할 작업을 명시한다. -p 또는 --pod 파라미터 뒤에 start, end, clean 중 하나를 반드시 입력해야 한다.

start 작업#

Altibase 이중화 객체를 생성하고 데이터를 동기화하는 작업을 수행한다. 파드를 생성할 때 이용한다. start 명령의 상세 동작을 살펴보자.

마스터 파드(pod_name-0) 생성하기#

Altibase 이중화 객체는 모든 파드에 생성해야 하므로 스테이트풀셋에서 pod_name-0을 생성할 때도 aku -p start 명령을 수행해야 한다.

① aku.conf 파일을 읽는다.

② /tmp 디렉토리에 aku_start_completed 파일이 있는지 확인한다. 일반적인 경우 기존에 aku -p start 명령이 실행되지 않았으므로 이 파일은 존재하지 않는다. 만약 존재할 경우, aku -p start 명령을 중복으로 실행한 것으로 판단하여 오류 메시지를 출력하고 종료한다.

③ 이중화 대상 서버인 모든 파드에 접속을 시도한다. 일반적인 경우 처음 생성된 파드이기 때문에 다른 파드와의 연결은 실패한다. 이는 정상적인 동작이니 무시해도 된다.

④ Altibase 이중화 객체를 생성한다. 만약, 같은 이름의 이중화 객체가 존재한다면 이중화 생성 단계는 생략한다.

⑤ pod_name-0 에서 접속에 성공한 모든 파드와 관련된 이중화를 시작하고, 접속된 다른 파드에서 pod_name-0과 관련된 이중화를 시작한다. 일반적인 경우 처음 생성된 파드이기 때문에 접속된 파드가 없어, 이 동작은 수행되지 않는다.

⑥ /tmp 디렉토리에 aku_start_completed 파일을 생성한다.

스케일 업(Scale up)#

마스터 파드가 생성된 상태에서 스케일 업을 하면 슬레이브 파드가 생성된다. 하나의 파드는 생성과 종료를 반복할 수 있는데, 파드가 처음 생성될 때와 종료 후 다시 시작될 때 aku -p start 동작이 다르다.

슬레이브 파드를 처음 생성하거나, 다시 시작할 때 (AKU_REPLICATION_RESET_AT_END = 1, 기본 동작)#

슬레이브 파드를 처음 생성하거나, 종료된 슬레이브 파드를 다시 시작하는 경우 aku -p start 명령이 aku에서 동작하는 과정을 설명한다.

아래는 pod_name-1에서 수행한 예이다.

① aku.conf 파일을 읽는다.

② /tmp 디렉토리에 aku_start_completed 파일이 있는지 확인한다. 일반적인 경우 기존에 aku -p start 명령이 실행되지 않았으므로 이 파일은 존재하지 않는다. 만약 존재할 경우, aku -p start 명령을 중복으로 실행한 것으로 판단하여 오류 메시지를 출력하고 종료한다.

③ 이중화 대상 서버인 모든 파드에 접속을 시도한다. 일반적인 경우 pod_name-0과의 접속만 성공하고 pod_name-2, pod_name-3은 생성되지 않았기 때문에 접속에 실패한다.

④ Altibase 이중화 객체를 생성한다. pod_name-1이 다시 시작된 파드라면, 같은 이름의 이중화 객체가 존재할 수 있으며 이 단계는 생략된다.

⑤ pod_name-1의 이중화 대상 테이블을 대상으로 TRUNCATE를 수행한다.

⑥ pod_name-0에게 이중화 SYNC를 요청한다.

⑦ pod_name-0에서 pod_name-1로 이중화 SYNC를 수행하고 이중화를 시작한다.

⑧ pod_name-1에서 접속에 성공한 모든 파드와 관련된 이중화를 시작하고, 접속된 다른 파드에서 pod_name-1과 관련된 이중화를 시작한다. 일반적인 경우 pod_name-0과 관련한 이중화(AKU_REP_01)만 pod_name-0 및 pod_name-1 파드에서 시작된다.

⑨ pod_name-1의 Altibase 서버 프로퍼티 ADMIN_MODE를 0으로 설정하여 데이터베이스 사용자의 접속을 허용한다.

⑩ /tmp 디렉토리에 aku_start_completed 파일을 생성한다.

이중화 정보가 초기화되지 않은 슬레이브 파드를 다시 시작할 때 (AKU_FLUSH_AT_START = 1, 기본 동작)#

파드가 비정상적으로 종료되거나 AKU_REPLICATION_RESET_AT_END 프로퍼티를 0으로 설정하고 종료하면 이중화 정보가 초기화 되지 않는다. 이중화 정보를 초기화 하지 않으면 Altibase에 이전의 이중화 정보가 남아 있어 파드를 다시 시작할 때 다른 노드로부터 데이터를 동기화(이중화 대상 테이블의 TRUNCATE 후 이중화 SYNC 수행)하지 않고, 자기 노드에서 다른 노드로의 데이터 동기화(FLUSH)만 수행한다. 아래는 이러한 경우, pod_name-1에서 aku -p start를 수행할 때의 aku 동작을 설명한다.

참고로, 이중화 정보가 초기화 되지 않으면 이중화 관련 메타 테이블에 이중화 재시작 지점(XSN)이 -1이 아닌 값을 갖는다. 보다 자세한 내용은 주의사항 7번을 참고한다.

① aku.conf 파일을 읽는다.

② /tmp 디렉토리에 aku_start_completed 파일이 있는지 확인한다. 일반적인 경우 기존에 aku -p start 명령이 실행되지 않았으므로 이 파일은 존재하지 않는다. 만약 존재할 경우, aku -p start 명령을 중복으로 실행한 것으로 판단하여 오류 메시지를 출력하고 종료한다.

③ 이중화 대상 서버인 모든 파드에 접속을 시도한다. 일반적인 경우 pod_name-0과의 접속만 성공한다.

④ pod_name-1에서 접속에 성공한 모든 파드와 관련된 이중화를 시작하고, 접속된 다른 파드에서 pod_name-1과 관련된 이중화를 시작한다. 일반적인 경우 pod_name-0과 관련한 이중화(AKU_REP_01)만 pod_name-0 및 pod_name-1 파드에서 시작된다.

⑤ pod_name-1에서 접속에 성공한 모든 파드와 관련된 이중화에 대해 ALTER REPLICATION ~ FLUSH ALL을 수행한다. 이 명령은 pod_name-1에서 다른 파드로 동기화하지 못한 데이터를 전송한다.

⑥ 접속된 다른 파드에서도 pod_name-1과 관련된 이중화에 대해 ALTER REPLICATION ~ FLUSH ALL을 수행하여 동기화되지 못한 데이터를 전송한다. 만약 aku 설정 파일에 AKU_FLUSH_TIMEOUT_AT_START 프로퍼티의 값이 0이 아니라면, ALTER_REPLICATION ~ FLUSH WAIT wait_time을 수행하여 pod_name-1로 동기화되지 못한 데이터를 전송한다.

⑦ pod_name-1의 Altibase 서버 프로퍼티 ADMIN_MODE를 0으로 설정하여 데이터베이스 사용자의 접속을 허용한다.

⑧ /tmp 디렉토리에 aku_start_completed 파일을 생성한다.

이중화 정보가 초기화되지 않은 슬레이브 파드를 다시 시작할 때 (AKU_FLUSH_AT_START = 0 일 때)#

비정상적으로 종료되었거나 AKU_REPLICATION_RESET_AT_END 프로퍼티를 0으로 설정하고 종료한 슬레이브 파드를 다시 시작할 때, AKU_FLUSH_AT_START 프로퍼티를 0으로 설정했다면 아래와 같이 동작한다.

① aku.conf 파일을 읽는다.

② /tmp 디렉토리에 aku_start_completed 파일이 있는지 확인한다. 일반적인 경우 기존에 aku -p start 명령이 실행되지 않았으므로 이 파일은 존재하지 않는다. 만약 존재할 경우, aku -p start 명령을 중복으로 실행한 것으로 판단하여 오류 메시지를 출력하고 종료한다.

③ 이중화 대상 서버인 모든 파드에 접속을 시도한다. 일반적인 경우 pod_name-0과의 접속만 성공한다.

④ pod_name-1에서 접속에 성공한 모든 파드와 관련된 이중화를 시작하고, 접속된 다른 파드에서 pod_name-1과 관련된 이중화를 시작한다. 일반적인 경우 pod_name-0과 관련한 이중화(AKU_REP_01)만 pod_name-0 및 pod_name-1 파드에서 시작된다.

⑤ pod_name-1의 Altibase 서버 프로퍼티 ADMIN_MODE를 0으로 설정하여 데이터베이스 사용자의 접속을 허용한다.

⑥ /tmp 디렉토리에 aku_start_completed 파일을 생성한다.

end 작업#

Altibase 이중화를 중지하고 초기화하는 작업을 수행한다. 파드를 종료할 때 이용한다.

① aku.conf 파일을 읽는다.

② 해당 파드와 이중화로 연결된 모든 파드에 접속을 시도한다. 해당 번호보다 높은 번호의 파드는 일반적인 경우 이미 삭제된 상태이기 때문에 접속이 실패할 수 있다. 이는 정상적인 동작이다.

③ 해당 파드의 이중화 객체에 ALTER REPLICATION replication_name FLUSH ALL 명령을 수행하여 변경 로그를 모두 전송한다. aku 설정 파일에서 AKU_FLUSH_AT_END 프로퍼티의 값이 0이라면 이 단계는 수행되지 않는다.

④ 해당 파드의 이중화 객체와 관련한 모든 파드에 ALTER REPLICATION replication_name STOP 수행을 요청한다.

⑤ 해당 파드의 이중화 객체와 관련한 모든 파드에 ALTER REPLICATION replication_name RESET 수행을 요청한다. aku 설정 파일에서 AKU_REPLICATION_RESET_AT_END 프로퍼티의 값이 0이라면 이 단계는 수행되지 않는다.

⑥ /tmp 디렉토리에서 aku_start_completed 파일을 삭제한다.

clean 작업#

파드에서 Altibase 이중화 객체를 모두 삭제하고, /tmp 디렉토리에서 aku_start_completed 파일을 삭제한다. 더 이상 파드 간에 동기화를 할 필요가 없을 때 사용한다.

주의사항#

aku 설정 파일 작성 시#

aku 프로퍼티 중 기본값이 없는 프로퍼티는 반드시 명시해야 한다. 명시하지 않을 경우, "Property [property_name] should be specified by configuration." 에러가 발생한다.
aku 설정 파일에 주석을 입력해야 할 경우 '#' 기호를 사용한다. 다만, '#' 뒤에 아무 내용이 없다면 구문 오류가 발생한다.

마스터 파드의 저장소에 손상이 발생한 경우#

aku는 마스터 파드의 저장소 손상으로 인한 데이터 손상을 복구할 수 없다.

aku -p start 명령 수행 시#

aku -p start 명령은 Altibase 서버가 정상적으로 시작된 후 수행해야 한다.
Altibase의 프로퍼티 중 ADMIN_MODE와 REMOTE_SYSDBA_ENABLE를 모두 1로 설정한 후 서버를 기동해야 한다.
하나의 파드에서 aku -p start 명령을 완료한 후 순차적으로 다음 파드를 생성해야 한다. 동시에 여러 파드에서 aku -p start를 수행하는 경우 aku가 정상적으로 동작하지 않을 수 있다. 이를 위해 startup probe를 설정해야 하며, aku_start_completed 파일의 존재 여부로 확인한다. 또한 publishNotReadyAddresses를 true로 설정해야한다. startup probe, publishNotReadyAddresses에 대한 자세한 내용은 쿠버네티스 공식 문서를 참고한다.

마스터 파드 장애 발생 시#

마스터 파드 장애란 다음과 같은 환경에서 마스터 파드에 aku -p start 명령이 실패하는 것을 말한다.

한 개 이상의 슬레이브 파드가 실행 중이다.
마스터 파드에 존재하는 이중화 객체 중 실행 중인 슬레이브 파드(들) 사이의 이중화 객체 정보가 일부, 또는 전부 유실되었다.

마스터 파드 장애가 발생하면 다음과 같이 마스터 파드를 복구해야 한다.

복구 기준이 될 슬레이브 파드를 선택한다. 복구 기준이 되는 슬레이브 파드 외의 모든 슬레이브 파드는 aku -p end 명령을 수행하여 종료한다.
슬레이브 파드로부터 마스터 파드로의 동기화를 수행하여 데이터 정합성을 맞춘다.
마스터 파드에서 이중화를 시작한다.
aku -p start 명령을 다시 수행한다.

각 복구 단계의 자세한 내용은 아래의 마스터 파드 장애 복구 예시를 참고한다.

마스터 파드 장애 상황 및 복구 예시#

다음과 같은 환경에서 마스터 파드 pod_name-0에서 장애가 발생했다고 가정한다.

설정 정보#

마스터 파드의 aku 프로퍼티 설정
- AKU_SERVER_COUNT = 4
- REPLICATION_NAME_PREFIX = AKU_REP
마스터 파드의 Altibase 서버 프로퍼티 설정
- ADMIN_MODE = 1

장애 상황#

슬레이브 파드 pod_name-1가 실행 중이다.
이중화 대상 테이블은 T1, T2, 그리고 T3이다.
마스터 파드에서 슬레이브 파드 pod_name-1 사이의 이중화 객체 AKU_REP_01의 정보가 소실되었다.

마스터 파드 장애 상황은 아래의 로그를 통해 확인할 수 있다.

$ aku -p start
AKU started with START option.
[AKU][2024/04/19 19:21:31.012670][140276343642368] [INFO][akuRunStart:828][-][-] Start as MASTER Pod.
[AKU][2024/04/19 19:21:31.012991][140276343642368] [ERROR][akuRunStart:1030][-][-] The MASTER server is detected to have     failed. Check and perform a manual recovery.
AKU failed to run.

이 때 마스터 파드에서 정보가 소실된 이중화 객체의 XSN을 조회하면 그 값이 -1로 출력된다.
```
iSQL> SELECT REPLICATION_NAME, XSN FROM SYSTEM_.SYS_REPLICATIONS_;
REPLICATION_NAME                XSN                  
--------------------------------------------------------
AKU_REP_01                      -1
1 rows selected.
```
XSN은 송·수신 쓰레드를 통해 원격 서버와 지역 서버에 이중화 정보를 전달하는 XLog의 식별 번호이다. 이중화 객체를 초기화 하면 이 값은 -1이 된다. 이 때 아래의 복구 절차를 순차적으로 수행하여 마스터 파드의 장애를 해결할 수 있다.

복구 절차#

슬레이브 파드에서 마스터 파드로 동기화를 수행하여 데이터 정합성을 맞춘다.

1-1. 마스터 파드에서 이중화 대상 테이블 레코드를 삭제한다.

데이터 동기화 시 충돌이 발생하는 것을 방지하기 위해 마스터 파드에서 관리하는 이중화 대상 테이블을 TRUNCATE 한다. TRUNCATE 명령을 수행하기 위해서는 Altibase 서버 프로퍼티REPLICATION_DDL_ENABLE를 1로 설정해야 한다.

-- REPLICATION_DDL_ENABLE 프로퍼티 설정을 1로 변경한다.
iSQL> ALTER SYSTEM SET REPLICATION_DDL_ENABLE = 1;
Alter success.

-- 이중화 대상 테이블의 레코드를 TRUNCATE 한다.
iSQL> TRUNCATE TABLE T1;
Truncate success.
iSQL> TRUNCATE TABLE T2;
Truncate success.
iSQL> TRUNCATE TABLE T3;
Truncate success.

-- REPLICATION_DDL_ENABLE 프로퍼티 설정을 0으로 원복한다.
iSQL> ALTER SYSTEM SET REPLICATION_DDL_ENABLE = 0;
Alter success.

1-2. 슬레이브 파드에서 데이터 동기화를 수행한다.

데이터를 동기화하기 전에, XSN 값을 초기화하기 위해 RESET을 수행한다. 동기화가 완료되면 이중화가 자동으로 시작된다.

-- 슬레이브 파드에서 이중화를 중지한다.
-- 이중화가 시작되지 않은 경우 생략할 수 있다.
iSQL> ALTER REPLICATION AKU_REP_01 STOP;
Alter success.

-- 슬레이브 파드에서 마스터 파드와의 이중화 객체를 초기화한다.
iSQL> ALTER REPLICATION AKU_REP_01 RESET;
Alter success.

-- 이중화 SYNC를 수행하여 
-- 슬레이브 파드와 마스터 파드의 데이터 정합성을 맞춘다.
iSQL> ALTER REPLICATION AKU_REP_01 SYNC;
Alter success.

마스터 파드에서 이중화를 시작한다.

마스터 파드에서 이중화를 시작하여 소실되었던 이중화 객체 정보의 복구를 완료한다.
```
iSQL> ALTER REPLICATION AKU_REP_01 START;
Alter success.
```

aku -p start 명령을 다시 수행한다.

복구가 완료된 마스터 파드는 슬레이브 파드와 동일한 데이터를 갖고 있고, 마스터 파드와 슬레이브 파드 사이의 이중화 객체인 AKU_REP_01의 XSN 값도 갱신된다. 이제 aku -p start 명령을 다시 수행하면 정상적으로 처리된다.

# aku.conf를 읽어 이중화 객체를 생성한다. 
$ aku -p start
AKU started with START option.
[AKU][2024/04/19 19:21:01.011887][139922191153408] [INFO][akuRunStart:828][-][-] Start as MASTER Pod.

# 마스터 파드와 슬레이브 파드의 이중화 갭을 제거한다.
[AKU][2024/04/19 19:21:09.057372][139922191153408] [INFO][akuRunStart:891][-][-] Flush replications.
[AKU][2024/04/19 19:21:09.086363][139922191153408] [INFO][akuRunStart:896][-][-] Replication flush has ended.

# 정상적으로 모든 절차가 수행된 뒤 aku가 종료된다. 
AKU run successfully.

aku -p end 명령 수행 시#

aku -p end 명령은 Altibase 서버를 중지하기 전에 수행해야 한다.
aku -p end 명령 수행이 완료된 후 파드를 종료해야 한다.

aku -p end 명령이 완료되기 전에 파드가 종료된 경우 1#

aku -p end 명령이 완료되기 전에 파드가 종료되었거나 AKU_REPLICATION_RESET_AT_END 프로퍼티를 0으로 설정하고 파드를 종료했다면 이중화 정보가 초기화되지 않고 남아 있을 수 있다. 이 경우 해당 파드가 다시 시작할 때 이중화 객체 생성과 이중화 대상 테이블을 TRUNCATE 하는 작업이 생략되고 이전에 생성한 이중화가 자동으로 시작된다. AKU_REPLICATION_RESET_AT_END 프로퍼티를 1으로 설정하고 aku -p end 명령이 정상적으로 수행될 때의 출력 결과는 예시 4를 확인해 보자.

aku -p end 명령이 완료되기 전에 파드가 종료된 경우 2#

aku -p end 명령이 완료되기 전에 파드가 종료되었거나 AKU_REPLICATION_RESET_AT_END 프로퍼티를 0으로 설정하고 파드를 종료한 상태가 장기간 지속된다면 종료된 파드뿐 아니라 다른 파드에도 이중화 정보가 초기화되지 않고 남아 있을 수 있다. 이 경우 다른 파드는 종료된 파드로 이중화 하기 위해 이중화에 필요한 온라인 로그 파일을 삭제하지 않는다. 온라인 로그 파일이 쌓이면 디스크 풀 발생으로 Altibase 서버가 정상적으로 운영되지 못할 수 있다. 따라서 이런 상황을 방지하기 위해 aku -p end 명령이 완전히 완료되기 전에 파드가 종료되었거나, AKU_REPLICATION_RESET_AT_END 프로퍼티를 0으로 설정하고 파드를 종료한 상태가 장기간 지속되고 있다면 이중화를 중지하고 이중화 초기화 작업을 진행해야 한다.

ALTER REPLICATION replication_name STOP;
ALTER REPLICATION replication_name RESET;

pod_name-0과 pod_name-1을 운영하던 중에 pod_name-1에서 aku -p end 명령이 정상적으로 수행되지 못하고 종료되었다고 가정해 보자. 이 때 pod_name-0에서 SYSTEM_.SYS_REPLICATIONS_의 XSN을 조회하면 pod_name-0과 pod_name-1의 이중화 객체인 AKU_REP_01의 XSN 값이 -1이 아닌 다른 값으로 출력된다. 이는 이중화 정보가 초기화되지 않은 것을 의미한다.

iSQL> SELECT REPLICATION_NAME, XSN FROM SYSTEM_.SYS_REPLICATIONS_;
REPLICATION_NAME                XSN                  
--------------------------------------------------------
AKU_REP_03                      -1
AKU_REP_02                      -1
AKU_REP_01                      859070110
3 rows selected.

pod_name-0에서 AKU_REP_01을 중지하고 이중화 객체를 생성한 시점으로 초기화한다.

iSQL> ALTER REPLICATION AKU_REP_01 STOP;
Alter sucess.

iSQL> ALTER REPLICATION AKU_REP_01 RESET;
Alter sucess.

다시 pod_name-0에서 SYSTEM_.SYS_REPLICATIONS_의 XSN을 조회해 보자. 이중화 객체 AKU_REP_01의 XSN 값이 -1으로 변경되었다.

iSQL> SELECT REPLICATION_NAME, XSN FROM SYSTEM_.SYS_REPLICATIONS_;
REPLICATION_NAME                XSN                  
--------------------------------------------------------
AKU_REP_03                      -1
AKU_REP_02                      -1
AKU_REP_01                      -1
3 rows selected.

제약사항#

aku 유틸리티를 안정적으로 사용하기 위해 쿠버네티스 환경 설정 시 반드시 지켜야 할 조건이다.

쿠버네티스의 워크로드 컨트롤러 중 스테이트풀셋에서만 사용해야 한다.
Altibase 서버와 aku는 같은 컨테이너에서 실행해야 한다.
파드 관리 정책은 OrderedReady 여야 한다. OrderedReady는 스테이트풀셋의 기본 정책이다.
스케일 업할 수 있는 레플리카는 최대 6개이다.
파드 종료 시 aku 수행을 완료할 수 있는 시간을 확보해야 한다. 따라서, 쿠버네티스에서 파드를 강제 종료하는 대기 시간인 terminationGracePeriodSeconds를 충분히 크게 설정해야 한다.

사용 예#

이 장에서는 다양한 상황에서 aku를 사용하는 예제를 설명한다.

예제에서 확인할 수 있는 aku 로그의 정보는 다음과 같다.

[AKU][현재 날짜 시간][스레드 번호] [메시지 타입][코드 정보][대상 pod 이름][이중화 이름] 메시지

예시 1: -i 파라미터와 함께 aku 실행#

-i 파라미터를 사용하여 aku를 실행한 결과이다. 아래 결과는 aku 설정 파일의 aku.conf.sample로 구성한 aku.conf에서 수행한 예시이다. Server ID가 0인 것은 스테이트풀셋 컨트롤러에서 처음 생성한 파드를 의미한다.

$ aku -i
 #########################
 [ Server ]
  Server ID        : 0
  Host             : AKUHOST-0.altibase-svc
  User             : SYS
  Password         : manager
  Port             : 20300
  Replication Port : 20301
  Max Server Count : 4
 #########################
 [ Replications ]
 #### Serve[ID:0] Replication list ####
  Replication Name : AKU_REP_01
  Replication Name : AKU_REP_02
  Replication Name : AKU_REP_03
 #### Serve[ID:1] Replication list ####
  Replication Name : AKU_REP_01
  Replication Name : AKU_REP_12
  Replication Name : AKU_REP_13
 #### Serve[ID:2] Replication list ####
  Replication Name : AKU_REP_02
  Replication Name : AKU_REP_12
  Replication Name : AKU_REP_23
 #### Serve[ID:3] Replication list ####
  Replication Name : AKU_REP_03
  Replication Name : AKU_REP_13
  Replication Name : AKU_REP_23
 #########################
 [ Replication Items ]
  User Name        : SYS
  Table Name       : T1

  User Name        : SYS
  Table Name       : T2
  Partition Name   : P1

  User Name        : SYS
  Table Name       : T3
 #########################

예시 2: 마스터 파드에서 start 명령 수행#

마스터 파드(pod_name-0)에서 aku -p start를 수행한 예시이다.

$ aku -p start
AKU started with START option.
[AKU][2024/03/18 12:34:58.136944][140708807235840] [INFO][akuRunStart:828][-][-] Start as MASTER Pod.
AKU run successfully.

출력 결과를 살펴보자.

# aku.conf를 읽어 이중화 객체를 생성한다. 
# START option은 aku -p start 를 사용함을 의미한다.
AKU started with START option.

# MASTER Pod는 첫 번째 파드를 의미한다. 
[AKU][2024/03/18 12:34:58.136944][140708807235840] [INFO][akuRunStart:828][-][-] Start as MASTER Pod.

# 정상적으로 모든 절차가 수행된 뒤 aku가 종료된다. 
AKU run successfully.

예시 3: 슬레이드 파드에서 start 명령 수행#

네 번째 파드(pod_name-3)에서 aku -p start 명령을 수행한 예시이다. Master Pod는 스테이트풀셋에서 생성한 첫 번째 파드를 의미한다.

$ aku -p start
AKU started with START option.
[AKU][2024/03/18 14:01:59.604647][140678415444224] [INFO][akuRunStart:903][-][-] Start as SLAVE Pod.
[AKU][2024/03/18 14:02:01.005068][140678415444224] [INFO][akuRunStart:959][-][-] Truncate tables for replications.
[AKU][2024/03/18 14:02:01.025100][140678415444224] [INFO][akuRunStart:964][-][-] Table truncation has ended.
[AKU][2024/03/18 14:02:01.025877][140678415444224] [INFO][akuRunStart:975][-][-] Sync tables from MASTER Server.
[AKU][2024/03/18 14:02:05.045135][140678415444224] [INFO][akuRunStart:980][-][-] Replication sync has ended.
AKU run successfully.

출력 결과를 살펴보자.

# aku.conf를 읽어 이중화 객체를 생성한다. 
# START option은 aku -p start 를 사용함을 의미한다.
 AKU started with START option.

# SLAVE Pod는 첫 번째 파드가 아닌 다른 파드를 의미한다. 
[AKU][2024/03/18 14:01:59.604647][140678415444224] [INFO][akuRunStart:903][-][-] Start as SLAVE Pod.

# SYNC 시 레코드 충돌 방지를 위해 대상 테이블의 레코드를 모두 삭제한다.
[AKU][2024/03/18 14:02:01.005068][140678415444224] [INFO][akuRunStart:959][-][-] Truncate tables for replications.
[AKU][2024/03/18 14:02:01.025100][140678415444224] [INFO][akuRunStart:964][-][-] Table truncation has ended.

# MASTER Server는 첫 번째 파드(pod_name-0)의 Altibase 서버를 말하며 해당 서버의 데이터를 로컬 파드로 동기화한다.
[AKU][2024/03/18 14:02:01.025877][140678415444224] [INFO][akuRunStart:975][-][-] Sync tables from MASTER Server.
[AKU][2024/03/18 14:02:05.045135][140678415444224] [INFO][akuRunStart:980][-][-] Replication sync has ended.

# 정상적으로 모든 절차가 수행된 뒤 aku가 종료된다. 
AKU run successfully.

예시 4: 슬레이브 파드에서 end 명령 수행#

네 번째 파드에서 AKU_REPLICATION_RESET_AT_END 프로퍼티를 1으로 설정하고 aku -p end 명령을 수행할 때의 출력 결과이다. 이중화 FLUSH 및 RESET 명령이 수행된 것을 볼 수 있다.

$ aku -p end
AKU started with END option.
[AKU][2024/03/18 14:02:49.246961][139626938108160] [INFO][akuRunEnd:1090][-][-] Start as SLAVE Pod.
[AKU][2024/03/18 14:02:49.247094][139626938108160] [INFO][akuRunEnd:1095][-][-] Flush replications.
[AKU][2024/03/18 14:02:49.247731][139626938108160] [INFO][akuRunEnd:1100][-][-] Replication flush has ended.
[AKU][2024/03/18 14:02:52.001848][139626938108160] [INFO][akuRunEnd:1114][-][-] Reset replications.
[AKU][2024/03/18 14:02:52.014300][139626938108160] [INFO][akuRunEnd:1119][-][-] Replication reset has ended.
AKU run successfully.

출력 결과를 살펴보자.

# aku.conf를 읽어 이중화를 중지하고 초기화한다. 
# END option은 aku -p end 를 사용함을 의미한다.
AKU started with END option.

# SLAVE Pod는 첫 번째 파드가 아닌 다른 파드를 의미한다. 
[AKU][2024/03/18 14:02:49.246961][139626938108160] [INFO][akuRunEnd:1090][-][-] Start as SLAVE Pod.

# 전달되지 않은 변경사항을 다른 파드로 FLUSH 한다.
[AKU][2024/03/18 14:02:49.247094][139626938108160] [INFO][akuRunEnd:1095][-][-] Flush replications.
[AKU][2024/03/18 14:02:49.247731][139626938108160] [INFO][akuRunEnd:1100][-][-] Replication flush has ended.

# 로컬 파드의 AKU 에서 생성한 이중화 객체를 모두 초기화한다.
[AKU][2024/03/18 14:02:52.001848][139626938108160] [INFO][akuRunEnd:1114][-][-] Reset replications.
[AKU][2024/03/18 14:02:52.014300][139626938108160] [INFO][akuRunEnd:1119][-][-] Replication reset has ended.

# 정상적으로 모든 절차가 수행된 뒤 aku가 종료된다. 
AKU run successfully.