백업과 복구

QueryPie ACP 설치 환경의 장애, 데이터유실을 대비하여, 시스템 전체에 대한 백업과 복구 절차를 안내합니다.

개요

QueryPie ACP는 일반적인 상태 저장형 웹애플리케이션과 유사한 특성을 갖고 있습니다. 백업과 복구는 일반적인 웹애플리케이션의 백업과 복구 절차와 동등하다고 간주하면 됩니다.

QueryPie ACP는 컨테이너로 실행되며, 주요 상태 정보는 MySQL 데이터베이스에 저장합니다. 따라서 시스템 복구를 위해서는 QueryPie가 사용하는 데이터베이스와 컨테이너 실행에 필요한 설정 정보를 함께 백업해야 합니다.

시스템 설정, 구성에 따라, 외부 시스템과 연계하는 경우, 해당 외부시스템을 백업, 복구하는 것이 필요합니다. 특히, Secret Store를 HashiCorp Vault, AWS Secrets Manager 등 외부 시스템에 둔 경우, 복구 이후에 Secret Store에 접근할 수 있어야 합니다.

백업과 복구 대상

QueryPie ACP 를 운영하는 시스템의 장애를 대비하고, 복구를 수행하기 위해 필요한 백업의 대상은 다음과 같습니다.

QueryPie ACP 를 위한 MySQL Database

QueryPie ACP 는 MySQL Database 에 이용자 계정, 접근 대상 Database 나 Server 등 자산 현황, 해당 시스템에 접근하기 위한 비밀정보, 접근제어 정책, 접근 로그 기록을 보관합니다. 이러한 데이터는 3개의 논리적인 Database 로 구분되며, 각각의 역할은 다음과 같습니다.

querypie
- 접근제어 대상과 정책 정보를 저장합니다. QueryPie Meta DB 라고 지칭합니다. 이용자 계정, 접근 대상이 되는 자산, 해당 시스템에 접근하기 위한 비밀정보, 접근제어 정책 등 ACP 를 운영하는데 필요한 대부분의 데이터는 이 데이터베이스에 저장됩니다.
querypie_snapshot
- 이용자가 대상 시스템에 접속하여 SQL Query 를 실행하거나 시스템에 접근하여 활동하는 기록을 일시적으로 보관합니다. 접속 세션이 살아있는 동안 사용되며, 접속 세션이 종료되면 querypie_log 로 이관됩니다. 이 데이터베이스는 DDL 은 복원되어야 하지만, 데이터 자체는 복원하지 않아도 무방하며, 백업 후 복구된 데이터는 무시됩니다.
querypie_log
- 감사기록을 저장합니다. 이용자가 Database, Server 등 자산에 접속한 기록, 이용자의 활동 내역이 기록됩니다.

감사기록을 보관하는 목적으로는, 이 3개 Database 를 모두 백업하여 보관하여야 합니다. 감사기록을 보관하지 않고, 장애 복구시, 접근 제어 기능을 빠르게 복구하는 목적으로는 querypie 데이터베이스를 백업하여 보관하면 됩니다. 데이터베이스에 대한 백업은 일반적인 MySQL Database 백업, 복구를 위한 도구를 사용하면 됩니다.

컨테이너 실행을 위한 정보

QueryPie ACP 컨테이너를 정상적으로 복구하려면 컨테이너 실행에 사용하는 환경 변수와 마운트 파일을 함께 백업해야 합니다. 자세한 환경 변수는 컨테이너 환경변수문서를 참조하십시오.

다음 정보를 포함하여 실제 운영 환경의 컨테이너 설정 전체를 보관합니다.

컨테이너 환경변수 - 데이터베이스와 Redis 연결 정보
컨테이너 환경변수 - KEY_ENCRYPTION_KEY
TLS 인증서와 Private Key
외부 시스템 연결 정보
컨테이너에 마운트한 인증서와 설정 파일
QueryPie 컨테이너 이미지 버전과 이미지 자체

특히 KEY_ENCRYPTION_KEY는 백업 당시의 값을 그대로 보관해야 합니다. 이 값이 유실되거나 다른 값으로 복원되면 데이터베이스에 암호화되어 저장된 Connection 비밀번호, SSH Key 등의 비밀 정보를 사용할 수 없습니다.

환경 변수와 인증서에는 비밀번호와 Private Key가 포함될 수 있으므로 암호화된 저장소에 보관하고 접근 권한을 제한해야 합니다.

컨테이너 환경변수 가운데, AGENT_SECRET, REDIS_PASSWORD 는 복구 과정에서 변경할 수 있는 값입니다.

Custom JDBC Driver, TLS 인증서, DAC_SKIP_SQL_COMMAND_RULE_FILE (skip_command_config.json) 등 파일을 사용하는 경우, 이를 백업하고 복구하여야 합니다.

Secret Store 에 보관되는 정보

QueryPie ACP 에 내장된 Secret Store 가 아닌, 외부 Secret Store 를 사용하는 경우, 이 Secret Store 에 보관되는 정보를 유실하지 않고, 계속 접근할 수 있도록 유지하여야 합니다. Secret Store 연동에서 Hashicorp Vault, Microsoft Active Directory, AWS Secrets Manager 등에 비밀정보를 보관하도록 설정하는 경우, 이 시스템에 계속 접근할 수 있는지, 연결정보를 안전하게 보관하고, 복구 시에 연결이 가능한지, 사전에 검증해 두는 것을 권장합니다.

인프라 구성

ACP를 실행, 운영하기 위한 인프라 구성 정보를 백업, 복구할 수 있어야 합니다. VM에서 Compose 방식으로 실행하는지, Kubernetes 환경에서 실행하는지 등 인프라 구성에 따라 백업, 복구해야 할 정보가 다릅니다.

시스템 아키텍처와 네트워크 접근제어에서 안내하는 Application Load Balancer, Network Load Balancer 의 구성 현황, 접근허용 설정을 백업해 둘 필요가 있습니다. TLS 인증서를 사용하는 경우, 이를 복원하기 위한 절차를 준비해 두어야 합니다.

백업, 복구하지 않아도 되는 정보

QueryPie ACP 의 응답속도를 높이고, 여러 Container 가 원활히 작동할 수 있도록 캐시를 제공하고, 일시적인 데이터 공유에 활용되는 Redis 에 보관되는 정보는 백업, 복구의 대상이 아닙니다.

백업 범위의 요약표

QueryPie ACP를 복구하기 위해서는 데이터베이스와 컨테이너 실행 설정을 함께 백업해야 합니다. 데이터베이스별 백업 범위는 다음과 같습니다.

백업 대상	백업 범위	복구 목적
`querypie`	스키마와 데이터	계정, 자산, 비밀 정보, 접근제어 정책 및 시스템 설정
`querypie_log`	스키마와 데이터	접속 로그, 실행 로그 및 기타 감사기록
`querypie_snapshot`	스키마와 DDL	복구 후 새로운 세션을 처리하기 위한 DB 구조
컨테이너 실행 설정	전체 설정	QueryPie 서비스 재기동
`KEY_ENCRYPTION_KEY`	원본 값	암호화된 비밀 정보 복호화
외부 Secret Store	고객사 운영 정책에 따른 백업	복구된 QueryPie가 기존 Secret에 접근할 수 있도록 보장

querypie_snapshot의 데이터는 활성 세션에 종속됩니다. 서버 프로세스가 재시작되거나 컨테이너가 교체되면 기존 세션은 무효화되므로, 해당 데이터를 복원해도 세션을 복구할 수 없습니다. 따라서 스키마와 DDL만 백업하며 테이블 데이터는 백업하지 않아도 됩니다.

백업 절차

QueryPie ACP의 데이터베이스와 실행 설정은 동일한 시점의 하나의 백업 세트로 관리하는 것을 권장합니다.

운영 중인 QueryPie 컨테이너 이미지 버전과 실행 방식을 확인합니다.
QueryPie가 사용하는 querypie, querypie_snapshot, querypie_log 데이터베이스와 컨테이너 환경 변수, 인증서 및 마운트 파일의 위치를 확인합니다.
외부 Secret Store와 인프라 구성의 백업 상태를 확인합니다.
가능한 경우 QueryPie로 유입되는 신규 요청을 차단하거나 컨테이너를 중지하여 일관된 백업 시점을 확보합니다. 서비스를 중지할 수 없는 경우에는 MySQL이 제공하는 일관된 온라인 백업 또는 관리형 데이터베이스의 스냅샷 기능을 사용합니다.
백업 범위에 정의된 querypie, querypie_snapshot, querypie_log 데이터베이스를 동일한 백업 작업 또는 동일한 백업 주기에서 백업합니다.
컨테이너 환경 변수, 인증서, Custom JDBC Driver 및 기타 마운트 파일을 백업합니다.
외부 Secret Store와 인프라 구성 정보를 고객사의 운영 정책에 따라 백업합니다.
백업 완료 여부와 백업 파일의 무결성을 확인합니다.
백업 시각과 QueryPie 컨테이너 이미지 버전을 기록하고, 백업 파일을 운영 시스템과 분리된 저장소에 보관합니다.

mysqldump를 이용한 백업 예시

다음 예시는 QueryPie ACP가 사용하는 세 데이터베이스를 하나의 SQL 파일로 백업합니다. 꺾쇠괄호로 표시된 값은 실제 MySQL 접속 정보로 변경하십시오.


mysqldump \
  --host="<MYSQL_HOST>" \
  --port="<MYSQL_PORT>" \
  --user="<MYSQL_USER>" \
  --password \
  --single-transaction \
  --hex-blob \
  --routines \
  --databases querypie querypie_snapshot querypie_log \
  > "querypie-backup-$(date +%Y%m%d-%H%M%S).sql"

--password 옵션을 사용하면 명령 실행 후 비밀번호 입력 프롬프트가 표시됩니다. 비밀번호가 셸 기록이나 프로세스 목록에 노출될 수 있으므로 명령행에 비밀번호 값을 직접 입력하지 않습니다.

--single-transaction은 트랜잭션을 지원하는 테이블을 일관된 시점으로 백업하는 데 사용합니다. 백업 중에는 스키마 변경 작업을 수행하지 않는 것을 권장합니다.

--routines는 일부 이전 QueryPie 버전에서 사용하는 stored procedure를 포함하여 백업하기 위해 지정합니다. QueryPie 기본 구성에서는 MySQL Event를 생성하지 않으므로 --events는 사용하지 않습니다. 고객이 별도의 Event를 생성한 경우에만 --events를 추가하십시오.

백업 계정에는 세 데이터베이스를 조회하고 스키마를 덤프하는 데 필요한 권한이 있어야 합니다. 명령의 종료 상태와 생성된 파일의 크기를 확인하고, 생성된 SQL 파일은 비밀 정보와 감사 로그가 포함된 중요 자료로 취급하여 안전하게 보관하십시오.

복구 절차

백업 당시와 동일한 QueryPie 컨테이너 이미지 버전과 실행 환경을 준비합니다.
MySQL과 Redis를 준비하고 필요한 네트워크 접근을 구성합니다. Redis의 기존 데이터는 복원하지 않습니다.
데이터베이스 복원이 완료될 때까지 QueryPie 컨테이너를 기동하지 않습니다.
동일한 백업 세트에서 querypie, querypie_snapshot, querypie_log 데이터베이스를 복원합니다.
컨테이너 환경 변수, 인증서, Custom JDBC Driver 및 기타 마운트 파일을 복원합니다.
KEY_ENCRYPTION_KEY에는 반드시 백업 당시와 동일한 값을 적용합니다.
외부 Secret Store를 사용하는 경우 복구된 환경에서 해당 시스템에 접근할 수 있는지 확인합니다.
Load Balancer, 방화벽 및 접근허용 설정 등 인프라 구성을 복원합니다.
데이터베이스 연결 정보와 복원 상태를 확인한 후 QueryPie 컨테이너를 기동합니다.
QueryPie 기동 상태와 애플리케이션 로그를 확인합니다.

서버 프로세스가 재시작되거나 컨테이너가 교체되면 장애 전에 존재하던 사용자 세션은 복구되지 않습니다. 사용자는 다시 로그인하고 대상 시스템에 다시 접속해야 합니다.

mysql CLI를 이용한 복구 예시

다음 예시는 앞의 mysqldump 명령으로 생성한 SQL 파일을 MySQL에 복원합니다. 복원 작업을 시작하기 전에 QueryPie 컨테이너가 중지되어 있는지 확인하고, 꺾쇠괄호로 표시된 값과 백업 파일명을 실제 환경에 맞게 변경하십시오.


mysql \
  --host="<MYSQL_HOST>" \
  --port="<MYSQL_PORT>" \
  --user="<MYSQL_USER>" \
  --password \
  < "querypie-backup-YYYYMMDD-HHMMSS.sql"

백업 파일은 --databases 옵션으로 생성되었으므로 querypie, querypie_snapshot, querypie_log 데이터베이스 선택 정보가 파일에 포함되어 있습니다. 복구 계정에는 데이터베이스와 스키마를 생성하고 데이터를 복원하는 데 필요한 권한이 있어야 합니다.

명령의 종료 상태를 확인하고 오류가 없는 경우에만 QueryPie 컨테이너를 기동하십시오. 기존 데이터베이스에 복원하는 경우에는 복원 전에 현재 데이터를 별도로 백업하고, 별도의 환경에서 복구 절차를 검증하는 것을 권장합니다.

복구 후 확인

복구가 완료되면 다음 항목을 확인합니다.

QueryPie 컨테이너가 정상적으로 기동되는가
관리자 로그인이 가능한가
사용자와 그룹이 정상적으로 조회되는가
접근 대상 Database와 Server가 정상적으로 조회되는가
역할, 권한 및 접근제어 정책이 정상적으로 조회되는가
저장된 Connection 정보로 대상 시스템에 접속할 수 있는가
기존 접속 로그와 실행 로그 및 감사 로그의 상세 내용을 조회할 수 있는가
새로운 접속과 활동이 감사 로그에 정상적으로 기록되는가
외부 Secret Store를 사용하는 경우 정상적으로 접근할 수 있는가
Load Balancer와 네트워크 접근 경로가 정상적으로 동작하는가
애플리케이션 로그에 데이터베이스 연결 또는 초기화 오류가 없는가

주의사항

데이터베이스 백업에는 MySQL에서 제공하는 공식 백업 도구 또는 관리형 데이터베이스 서비스의 백업 기능을 사용합니다. 실행 중인 MySQL 데이터 파일을 일반 파일 복사 방식으로 백업하지 않습니다.
querypie, querypie_snapshot, querypie_log는 하나의 백업 세트로 관리하고 복구할 때도 동일한 세트를 사용합니다.
KEY_ENCRYPTION_KEY는 백업 당시와 동일한 값을 사용해야 합니다. 다른 값을 사용하면 암호화된 비밀 정보를 정상적으로 복호화할 수 없습니다.
데이터베이스 복원이 완료되기 전에 QueryPie 컨테이너를 기동하지 않습니다.
장애 전에 열려 있던 사용자 세션은 복구되지 않습니다.
백업 파일과 설정 정보는 운영 시스템과 분리된 저장소에 보관하고 접근 권한을 제한합니다.
백업 성공 여부만으로 복구 가능성을 보장할 수 없습니다. 별도의 환경에서 정기적으로 복구 절차를 검증하는 것을 권장합니다.
백업 당시와 다른 QueryPie 버전으로 복구하면서 업그레이드를 동시에 수행하지 않는 것을 권장합니다. 먼저 백업 당시 버전으로 복구한 후 별도의 업그레이드 절차를 진행합니다.