From be48fa633d11e803c1045bd82325b14f6188dc39 Mon Sep 17 00:00:00 2001 From: JK Date: Tue, 6 Oct 2026 16:07:30 +0900 Subject: [PATCH 1/2] =?UTF-8?q?mdx:=20=EB=B0=B1=EC=97=85=EA=B3=BC=20?= =?UTF-8?q?=EB=B3=B5=EA=B5=AC=20=EB=AC=B8=EC=84=9C=EB=A5=BC=20=EB=8F=99?= =?UTF-8?q?=EA=B8=B0=ED=99=94=ED=95=A9=EB=8B=88=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../etc/korean-titles-translations.txt | 1 + .../convert-manifest.qm.yaml | 4 + confluence-mdx/var/pages.qm.yaml | 13 ++ src/content/ko/installation/_meta.ts | 1 + .../ko/installation/backup-and-recovery.mdx | 200 ++++++++++++++++++ 5 files changed, 219 insertions(+) create mode 100644 src/content/ko/installation/backup-and-recovery.mdx diff --git a/confluence-mdx/etc/korean-titles-translations.txt b/confluence-mdx/etc/korean-titles-translations.txt index bbf0298bc..4fa936616 100644 --- a/confluence-mdx/etc/korean-titles-translations.txt +++ b/confluence-mdx/etc/korean-titles-translations.txt @@ -160,6 +160,7 @@ Reverse Tunnel을 통해 DB에 통신하기 | Communicating with DB through Reve # Installation 설치 | Installation 제품 설치 | Installation +백업과 복구 | Backup and Recovery 제품 버전 | Product Versions 설치 전 준비사항 | Prerequisites 리눅스 배포본과 Docker, Podman 지원 현황 | Linux Distribution and Docker, Podman Support Status diff --git a/confluence-mdx/var/convert-manifests/convert-manifest.qm.yaml b/confluence-mdx/var/convert-manifests/convert-manifest.qm.yaml index 58140db05..fcc401617 100644 --- a/confluence-mdx/var/convert-manifests/convert-manifest.qm.yaml +++ b/confluence-mdx/var/convert-manifests/convert-manifest.qm.yaml @@ -1089,6 +1089,10 @@ outputs: type: page kind: navigation path: installation/_meta.ts +- page_id: '2463465478' + type: page + kind: mdx + path: installation/backup-and-recovery.mdx - page_id: '954761289' type: page kind: mdx diff --git a/confluence-mdx/var/pages.qm.yaml b/confluence-mdx/var/pages.qm.yaml index 85998aa11..5b2a5f157 100644 --- a/confluence-mdx/var/pages.qm.yaml +++ b/confluence-mdx/var/pages.qm.yaml @@ -5383,6 +5383,19 @@ - "installation" - "server-configuration-requirements" - "server-configuration-requirements-summary" +- "page_id": "2463465478" + "type": "page" + "title": "백업과 복구" + "title_orig": "백업과 복구" + "breadcrumbs": + - "제품 설치" + - "백업과 복구" + "breadcrumbs_en": + - "Installation" + - "Backup and Recovery" + "path": + - "installation" + - "backup-and-recovery" - "page_id": "1239416833" "type": "page" "title": "QueryPie ACP Community Edition" diff --git a/src/content/ko/installation/_meta.ts b/src/content/ko/installation/_meta.ts index af4dee13e..d6b1168c8 100644 --- a/src/content/ko/installation/_meta.ts +++ b/src/content/ko/installation/_meta.ts @@ -7,5 +7,6 @@ export default { 'container-environment-variables': '컨테이너 환경변수', 'license-installation': '라이선스 설치', 'server-configuration-requirements': '서버구성 요구사항', + 'backup-and-recovery': '백업과 복구', 'querypie-acp-community-edition': 'QueryPie ACP Community Edition', }; diff --git a/src/content/ko/installation/backup-and-recovery.mdx b/src/content/ko/installation/backup-and-recovery.mdx new file mode 100644 index 000000000..9e4e944ec --- /dev/null +++ b/src/content/ko/installation/backup-and-recovery.mdx @@ -0,0 +1,200 @@ +--- +title: '백업과 복구' +confluenceUrl: 'https://querypie.atlassian.net/wiki/spaces/QM/pages/2463465478' +--- + +# 백업과 복구 + +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 로 이관됩니다. +* querypie_log + * 감사기록을 저장합니다. 이용자가 Database, Server 등 자산에 접속한 기록, 이용자의 활동 내역이 기록됩니다. + +감사기록을 보관하는 목적으로는, 이 3개 Database 를 모두 백업하여 보관하여야 합니다. +감사기록을 보관하지 않고, 장애 복구시, 접근 제어 기능을 빠르게 복구하는 목적으로는 `querypie` 데이터베이스를 백업하여 보관하면 됩니다. +데이터베이스에 대한 백업은 일반적인 MySQL Database 백업, 복구를 위한 도구를 사용하면 됩니다. + +#### 컨테이너 실행을 위한 정보 + +QueryPie ACP 컨테이너를 정상적으로 복구하려면 컨테이너 실행에 사용하는 환경 변수와 마운트 파일을 함께 백업해야 합니다. +자세한 환경 변수는 [컨테이너 환경변수](container-environment-variables)문서를 참조하십시오. + +다음 정보를 포함하여 실제 운영 환경의 컨테이너 설정 전체를 보관합니다. + +* 데이터베이스와 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 연동](../administrator-manual/general/system/integrations/integrating-with-secret-store)에서 Hashicorp Vault, Microsoft Active Directory, AWS Secrets Manager 등에 비밀정보를 보관하도록 설정하는 경우, 이 시스템에 계속 접근할 수 있는지, 연결정보를 안전하게 보관하고, 복구 시에 연결이 가능한지, 사전에 검증해 두는 것을 권장합니다. + +#### 인프라 구성 + +ACP를 실행, 운영하기 위한 인프라 구성 정보를 백업, 복구할 수 있어야 합니다. +VM에서 Compose 방식으로 실행하는지, Kubernetes 환경에서 실행하는지 등 인프라 구성에 따라 백업, 복구해야 할 정보가 다릅니다. + +[시스템 아키텍처와 네트워크 접근제어](system-architecture-and-network-access-control)에서 안내하는 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의 데이터베이스와 실행 설정은 동일한 시점의 하나의 백업 세트로 관리하는 것을 권장합니다. + +1. 운영 중인 QueryPie 컨테이너 이미지 버전과 실행 방식을 확인합니다. +2. QueryPie가 사용하는 `querypie`, `querypie_snapshot`, `querypie_log` 데이터베이스와 컨테이너 환경 변수, 인증서 및 마운트 파일의 위치를 확인합니다. +3. 외부 Secret Store와 인프라 구성의 백업 상태를 확인합니다. +4. 가능한 경우 QueryPie로 유입되는 신규 요청을 차단하거나 컨테이너를 중지하여 일관된 백업 시점을 확보합니다. 서비스를 중지할 수 없는 경우에는 MySQL이 제공하는 일관된 온라인 백업 또는 관리형 데이터베이스의 스냅샷 기능을 사용합니다. +5. 백업 범위에 정의된 `querypie`, `querypie_snapshot`, `querypie_log` 데이터베이스를 동일한 백업 작업 또는 동일한 백업 주기에서 백업합니다. +6. 컨테이너 환경 변수, 인증서, Custom JDBC Driver 및 기타 마운트 파일을 백업합니다. +7. 외부 Secret Store와 인프라 구성 정보를 고객사의 운영 정책에 따라 백업합니다. +8. 백업 완료 여부와 백업 파일의 무결성을 확인합니다. +9. 백업 시각과 QueryPie 컨테이너 이미지 버전을 기록하고, 백업 파일을 운영 시스템과 분리된 저장소에 보관합니다. + +#### mysqldump를 이용한 백업 예시 + +다음 예시는 QueryPie ACP가 사용하는 세 데이터베이스를 하나의 SQL 파일로 백업합니다. +꺾쇠괄호로 표시된 값은 실제 MySQL 접속 정보로 변경하십시오. +```bash +mysqldump \ + --host="" \ + --port="" \ + --user="" \ + --password \ + --single-transaction \ + --hex-blob \ + --databases querypie querypie_snapshot querypie_log \ + > "querypie-backup-$(date +%Y%m%d-%H%M%S).sql" +``` + +`--password` 옵션을 사용하면 명령 실행 후 비밀번호 입력 프롬프트가 표시됩니다. +비밀번호가 셸 기록이나 프로세스 목록에 노출될 수 있으므로 명령행에 비밀번호 값을 직접 입력하지 않습니다. + +`--single-transaction`은 트랜잭션을 지원하는 테이블을 일관된 시점으로 백업하는 데 사용합니다. +백업 중에는 스키마 변경 작업을 수행하지 않는 것을 권장합니다. + +백업 계정에는 세 데이터베이스를 조회하고 스키마를 덤프하는 데 필요한 권한이 있어야 합니다. +명령의 종료 상태와 생성된 파일의 크기를 확인하고, 생성된 SQL 파일은 비밀 정보와 감사 로그가 포함된 중요 자료로 취급하여 안전하게 보관하십시오. + +### 복구 절차 + +1. 백업 당시와 동일한 QueryPie 컨테이너 이미지 버전과 실행 환경을 준비합니다. +2. MySQL과 Redis를 준비하고 필요한 네트워크 접근을 구성합니다. Redis의 기존 데이터는 복원하지 않습니다. +3. 데이터베이스 복원이 완료될 때까지 QueryPie 컨테이너를 기동하지 않습니다. +4. 동일한 백업 세트에서 `querypie`, `querypie_snapshot`, `querypie_log` 데이터베이스를 복원합니다. +5. 컨테이너 환경 변수, 인증서, Custom JDBC Driver 및 기타 마운트 파일을 복원합니다. +6. `KEY_ENCRYPTION_KEY`에는 반드시 백업 당시와 동일한 값을 적용합니다. +7. 외부 Secret Store를 사용하는 경우 복구된 환경에서 해당 시스템에 접근할 수 있는지 확인합니다. +8. Load Balancer, 방화벽 및 접근허용 설정 등 인프라 구성을 복원합니다. +9. 데이터베이스 연결 정보와 복원 상태를 확인한 후 QueryPie 컨테이너를 기동합니다. +10. QueryPie 기동 상태와 애플리케이션 로그를 확인합니다. + +서버 프로세스가 재시작되거나 컨테이너가 교체되면 장애 전에 존재하던 사용자 세션은 복구되지 않습니다. +사용자는 다시 로그인하고 대상 시스템에 다시 접속해야 합니다. + +#### mysql CLI를 이용한 복구 예시 + +다음 예시는 앞의 `mysqldump` 명령으로 생성한 SQL 파일을 MySQL에 복원합니다. +복원 작업을 시작하기 전에 QueryPie 컨테이너가 중지되어 있는지 확인하고, 꺾쇠괄호로 표시된 값과 백업 파일명을 실제 환경에 맞게 변경하십시오. +```bash +mysql \ + --host="" \ + --port="" \ + --user="" \ + --password \ + < "querypie-backup-YYYYMMDD-HHMMSS.sql" +``` + +`--password` 옵션을 사용하면 명령 실행 후 비밀번호 입력 프롬프트가 표시됩니다. +비밀번호가 셸 기록이나 프로세스 목록에 노출될 수 있으므로 명령행에 비밀번호 값을 직접 입력하지 않습니다. + +백업 파일은 `--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 버전으로 복구하면서 업그레이드를 동시에 수행하지 않는 것을 권장합니다. 먼저 백업 당시 버전으로 복구한 후 별도의 업그레이드 절차를 진행합니다. From e175e63ed5cbe7b76f7b526ec63436ec3f2ae9a0 Mon Sep 17 00:00:00 2001 From: JK Date: Tue, 6 Oct 2026 16:10:23 +0900 Subject: [PATCH 2/2] =?UTF-8?q?mdx:=20=EB=B0=B1=EC=97=85=EA=B3=BC=20?= =?UTF-8?q?=EB=B3=B5=EA=B5=AC=20=EB=AC=B8=EC=84=9C=EB=A5=BC=20=EC=98=81?= =?UTF-8?q?=EC=96=B4=EC=99=80=20=EC=9D=BC=EB=B3=B8=EC=96=B4=EB=A1=9C=20?= =?UTF-8?q?=EB=B2=88=EC=97=AD=ED=95=A9=EB=8B=88=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/content/en/installation/_meta.ts | 1 + .../en/installation/backup-and-recovery.mdx | 200 ++++++++++++++++++ src/content/ja/installation/_meta.ts | 1 + .../ja/installation/backup-and-recovery.mdx | 200 ++++++++++++++++++ 4 files changed, 402 insertions(+) create mode 100644 src/content/en/installation/backup-and-recovery.mdx create mode 100644 src/content/ja/installation/backup-and-recovery.mdx diff --git a/src/content/en/installation/_meta.ts b/src/content/en/installation/_meta.ts index d87655c42..fac1ba4c8 100644 --- a/src/content/en/installation/_meta.ts +++ b/src/content/en/installation/_meta.ts @@ -7,5 +7,6 @@ export default { 'container-environment-variables': 'Container Environment Variables', 'license-installation': 'License Installation', 'server-configuration-requirements': 'Server Configuration Requirements', + 'backup-and-recovery': 'Backup and Recovery', 'querypie-acp-community-edition': 'QueryPie ACP Community Edition', }; diff --git a/src/content/en/installation/backup-and-recovery.mdx b/src/content/en/installation/backup-and-recovery.mdx new file mode 100644 index 000000000..616234a0d --- /dev/null +++ b/src/content/en/installation/backup-and-recovery.mdx @@ -0,0 +1,200 @@ +--- +title: 'Backup and Recovery' +confluenceUrl: 'https://querypie.atlassian.net/wiki/spaces/QM/pages/2463465478' +--- + +# Backup and Recovery + +This document explains how to back up and recover the entire QueryPie ACP system to prepare for failures and data loss in the installation environment. + +### Overview + +QueryPie ACP has characteristics similar to those of a typical stateful web application. +You can treat its backup and recovery process as equivalent to that of a typical web application. + +QueryPie ACP runs in containers and stores its primary state information in MySQL databases. +To recover the system, you must therefore back up both the databases used by QueryPie and the configuration required to run the containers. + +Depending on your system settings and configuration, you may also need to back up and recover integrated external systems. +In particular, if you use an external system such as HashiCorp Vault or AWS Secrets Manager for the Secret Store, you must be able to access the Secret Store after recovery. + +### Backup and Recovery Targets + +To prepare for a failure in the system running QueryPie ACP and perform recovery, back up the following targets. + +#### MySQL Databases for QueryPie ACP + +QueryPie ACP stores user accounts, assets such as target databases and servers, secrets for accessing those systems, access control policies, and access logs in MySQL databases. +This data is divided into three logical databases with the following roles. + +* querypie + * Stores access control targets and policy information. This database is referred to as the QueryPie Meta DB. Most of the data required to operate ACP, including user accounts, target assets, secrets for accessing those systems, and access control policies, is stored in this database. +* querypie_snapshot + * Temporarily stores records generated when users run SQL queries on target systems or perform activities after accessing those systems. The records remain while the connection session is active and are transferred to querypie_log when the session ends. +* querypie_log + * Stores audit records, including records of users accessing assets such as databases and servers and records of user activities. + +To retain audit records, back up all three databases. +If retaining audit records is not required and your goal is to quickly restore access control capabilities after a failure, you only need to back up the `querypie` database. +You can use standard MySQL database backup and recovery tools to back up the databases. + +#### Information Required to Run Containers + +To restore QueryPie ACP containers successfully, back up the environment variables and mounted files used to run the containers. +For details about the environment variables, see [Container Environment Variables](container-environment-variables). + +Retain the complete container configuration for the production environment, including the following information. + +* Database and Redis connection information +* KEY_ENCRYPTION_KEY +* TLS certificates and private keys +* External system connection information +* Certificates and configuration files mounted in the containers +* QueryPie container image version + +In particular, retain the exact value of `KEY_ENCRYPTION_KEY` used at the time of backup. +If this value is lost or restored with a different value, secrets encrypted in the database, such as connection passwords and SSH keys, cannot be used. + +Because environment variables and certificates may contain passwords and private keys, store them in an encrypted repository and restrict access to them. + +You can change AGENT_SECRET and REDIS_PASSWORD during the recovery process. + +If you use files such as a custom JDBC driver, TLS certificates, or DAC_SKIP_SQL_COMMAND_RULE_FILE (`skip_command_config.json`), back up and restore them as well. + +#### Information Stored in the Secret Store + +If you use an external Secret Store instead of the Secret Store built into QueryPie ACP, ensure that its data is not lost and remains accessible. When you configure secrets to be stored in HashiCorp Vault, Microsoft Active Directory, AWS Secrets Manager, or another system as described in [Integrating with Secret Store](../administrator-manual/general/system/integrations/integrating-with-secret-store), we recommend verifying in advance that the system will remain accessible, that its connection information is stored securely, and that it can be connected to after recovery. + +#### Infrastructure Configuration + +You must be able to back up and recover the infrastructure configuration used to run and operate ACP. +The information that must be backed up and recovered depends on your infrastructure, such as whether ACP runs on a VM using Compose or in a Kubernetes environment. + +Back up the Application Load Balancer and Network Load Balancer configurations and the access control settings described in [System Architecture and Network Access Control](system-architecture-and-network-access-control). +If you use TLS certificates, prepare a procedure for restoring them. + +#### Information That Does Not Need to Be Backed Up or Recovered + +The data stored in Redis, which provides caching to improve QueryPie ACP response times and supports smooth operation and temporary data sharing among multiple containers, does not need to be backed up or recovered. + +#### Summary of the Backup Scope + +To recover QueryPie ACP, back up both the databases and the container runtime configuration. +The backup scope for each database is as follows. + +| Backup Target | Backup Scope | Recovery Purpose | +| -------------------- | -------------------------------- | ----------------------------------------------------------------- | +| `querypie` | Schema and data | Accounts, assets, secrets, access control policies, and settings | +| `querypie_log` | Schema and data | Access logs, execution logs, and other audit records | +| `querypie_snapshot` | Schema and DDL | Database structure for processing new sessions after recovery | +| Container runtime configuration | Complete configuration | Restarting the QueryPie service | +| `KEY_ENCRYPTION_KEY` | Original value | Decrypting encrypted secrets | +| External Secret Store | Backup according to your operational policy | Ensuring that the recovered QueryPie instance can access existing secrets | + +The data in `querypie_snapshot` is tied to active sessions. +If the server process restarts or a container is replaced, existing sessions become invalid, and restoring this data does not restore those sessions. +Therefore, back up only the schema and DDL; you do not need to back up table data. + +### Backup Procedure + +We recommend managing the QueryPie ACP databases and runtime configuration as a single backup set captured at the same point in time. + +1. Check the QueryPie container image version and the method used to run the containers in production. +2. Identify the `querypie`, `querypie_snapshot`, and `querypie_log` databases used by QueryPie and the locations of the container environment variables, certificates, and mounted files. +3. Check the backup status of the external Secret Store and infrastructure configuration. +4. If possible, block new requests to QueryPie or stop the containers to establish a consistent backup point. If you cannot stop the service, use a consistent online backup provided by MySQL or a snapshot feature provided by a managed database service. +5. Back up the `querypie`, `querypie_snapshot`, and `querypie_log` databases defined in the backup scope within the same backup operation or backup cycle. +6. Back up the container environment variables, certificates, custom JDBC drivers, and other mounted files. +7. Back up the external Secret Store and infrastructure configuration according to your organization's operational policies. +8. Confirm that the backup completed and verify the integrity of the backup files. +9. Record the backup time and QueryPie container image version, and store the backup files in a location separate from the production system. + +#### Backup Example Using mysqldump + +The following example backs up the three databases used by QueryPie ACP to a single SQL file. +Replace the values in angle brackets with your actual MySQL connection information. +```bash +mysqldump \ + --host="" \ + --port="" \ + --user="" \ + --password \ + --single-transaction \ + --hex-blob \ + --databases querypie querypie_snapshot querypie_log \ + > "querypie-backup-$(date +%Y%m%d-%H%M%S).sql" +``` + +When you use the `--password` option, a password prompt appears after you run the command. +Do not enter the password directly on the command line because it may be exposed in the shell history or process list. + +The `--single-transaction` option creates a consistent point-in-time backup of tables that support transactions. +We recommend avoiding schema changes while the backup is running. + +The backup account must have the permissions required to read the three databases and dump their schemas. +Check the command's exit status and the size of the generated file, and treat the SQL file as sensitive because it contains secrets and audit logs. + +### Recovery Procedure + +1. Prepare the same QueryPie container image version and runtime environment used at the time of backup. +2. Prepare MySQL and Redis and configure the required network access. Do not restore the previous Redis data. +3. Do not start the QueryPie containers until database recovery is complete. +4. Restore the `querypie`, `querypie_snapshot`, and `querypie_log` databases from the same backup set. +5. Restore the container environment variables, certificates, custom JDBC drivers, and other mounted files. +6. Set `KEY_ENCRYPTION_KEY` to the exact value used at the time of backup. +7. If you use an external Secret Store, verify that it can be accessed from the recovered environment. +8. Restore the infrastructure configuration, including load balancers, firewalls, and access control settings. +9. After confirming the database connection information and recovery status, start the QueryPie containers. +10. Check the QueryPie startup status and application logs. + +If the server process restarts or a container is replaced, user sessions that existed before the failure are not restored. +Users must sign in again and reconnect to the target systems. + +#### Recovery Example Using the mysql CLI + +The following example restores an SQL file created with the preceding `mysqldump` command to MySQL. +Before starting the recovery, confirm that the QueryPie containers are stopped, and replace the values in angle brackets and the backup file name with values appropriate for your environment. +```bash +mysql \ + --host="" \ + --port="" \ + --user="" \ + --password \ + < "querypie-backup-YYYYMMDD-HHMMSS.sql" +``` + +When you use the `--password` option, a password prompt appears after you run the command. +Do not enter the password directly on the command line because it may be exposed in the shell history or process list. + +Because the backup file was created with the `--databases` option, it includes database selection information for `querypie`, `querypie_snapshot`, and `querypie_log`. +The recovery account must have the permissions required to create the databases and schemas and restore the data. + +Check the command's exit status, and start the QueryPie containers only if there are no errors. +If you restore an existing database, back up the current data first and verify the recovery procedure in a separate environment. + +### Post-Recovery Checks + +After recovery is complete, check the following items. + +* QueryPie containers start successfully +* Administrators can sign in +* Users and groups are displayed correctly +* Target databases and servers are displayed correctly +* Roles, permissions, and access control policies are displayed correctly +* Target systems can be accessed using the stored connection information +* Details of existing access logs, execution logs, and audit logs are available +* New access and activity are recorded correctly in audit logs +* External Secret Stores are accessible, if used +* Load balancers and network access paths work correctly +* Application logs contain no database connection or initialization errors + +### Precautions + +* Use an official backup tool provided by MySQL or the backup feature of a managed database service to back up the databases. Do not back up active MySQL data files by copying them as regular files. +* Manage `querypie`, `querypie_snapshot`, and `querypie_log` as one backup set and restore them from the same set. +* Use the same `KEY_ENCRYPTION_KEY` value that was in use at the time of backup. A different value prevents encrypted secrets from being decrypted correctly. +* Do not start the QueryPie containers until database recovery is complete. +* User sessions that were open before the failure are not restored. +* Store backup files and configuration information in a location separate from the production system and restrict access to them. +* A successful backup alone does not guarantee recoverability. We recommend regularly verifying the recovery procedure in a separate environment. +* We recommend restoring the backup with the QueryPie version used at the time of backup and performing any upgrade as a separate procedure afterward. diff --git a/src/content/ja/installation/_meta.ts b/src/content/ja/installation/_meta.ts index ead91f93a..5e39e40fe 100644 --- a/src/content/ja/installation/_meta.ts +++ b/src/content/ja/installation/_meta.ts @@ -7,5 +7,6 @@ export default { 'container-environment-variables': 'コンテナ環境変数', 'license-installation': 'ライセンスインストール', 'server-configuration-requirements': 'サーバ構成要件', + 'backup-and-recovery': 'バックアップとリカバリ', 'querypie-acp-community-edition': 'QueryPie ACP Community Edition', }; diff --git a/src/content/ja/installation/backup-and-recovery.mdx b/src/content/ja/installation/backup-and-recovery.mdx new file mode 100644 index 000000000..4aa9ac7e8 --- /dev/null +++ b/src/content/ja/installation/backup-and-recovery.mdx @@ -0,0 +1,200 @@ +--- +title: 'バックアップとリカバリ' +confluenceUrl: 'https://querypie.atlassian.net/wiki/spaces/QM/pages/2463465478' +--- + +# バックアップとリカバリ + +QueryPie ACP のインストール環境で発生する障害やデータ損失に備え、システム全体をバックアップおよびリカバリする手順について説明します。 + +### 概要 + +QueryPie ACP は、一般的なステートフル Web アプリケーションと同様の特性を持っています。 +バックアップとリカバリは、一般的な Web アプリケーションのバックアップおよびリカバリ手順と同等とみなすことができます。 + +QueryPie ACP はコンテナで実行され、主要な状態情報を MySQL データベースに保存します。 +そのため、システムをリカバリするには、QueryPie が使用するデータベースとコンテナの実行に必要な設定情報をあわせてバックアップする必要があります。 + +システムの設定や構成によっては、連携する外部システムもバックアップおよびリカバリする必要があります。 +特に、Secret Store として HashiCorp Vault や AWS Secrets Manager などの外部システムを使用している場合は、リカバリ後も Secret Store にアクセスできる必要があります。 + +### バックアップとリカバリの対象 + +QueryPie ACP を運用するシステムの障害に備えてリカバリを実行するには、次の対象をバックアップします。 + +#### QueryPie ACP 用の MySQL Database + +QueryPie ACP は、ユーザーアカウント、アクセス対象の Database や Server などの資産情報、対象システムへのアクセスに必要な秘密情報、アクセス制御ポリシー、およびアクセスログを MySQL Database に保存します。 +これらのデータは 3 つの論理的な Database に分かれており、それぞれの役割は次のとおりです。 + +* querypie + * アクセス制御の対象とポリシー情報を保存します。このデータベースは QueryPie Meta DB と呼ばれます。ユーザーアカウント、アクセス対象の資産、対象システムへのアクセスに必要な秘密情報、アクセス制御ポリシーなど、ACP の運用に必要なデータの大部分がこのデータベースに保存されます。 +* querypie_snapshot + * ユーザーが対象システムに接続して SQL Query を実行した記録や、システムにアクセスして行った操作の記録を一時的に保存します。接続セッションが有効な間に使用され、セッションが終了すると querypie_log に移行されます。 +* querypie_log + * 監査記録を保存します。ユーザーが Database や Server などの資産にアクセスした記録と、ユーザーの操作履歴が記録されます。 + +監査記録を保持する場合は、3 つの Database をすべてバックアップして保管します。 +監査記録を保持せず、障害発生時にアクセス制御機能を迅速に復旧することを目的とする場合は、`querypie` データベースのみをバックアップして保管します。 +データベースのバックアップには、一般的な MySQL Database のバックアップおよびリカバリツールを使用できます。 + +#### コンテナの実行に必要な情報 + +QueryPie ACP コンテナを正常にリカバリするには、コンテナの実行に使用する環境変数とマウントファイルをあわせてバックアップする必要があります。 +環境変数の詳細については、[コンテナ環境変数](container-environment-variables)を参照してください。 + +次の情報を含む、実際の運用環境のコンテナ設定全体を保管します。 + +* データベースと 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 連携](../administrator-manual/general/system/integrations/integrating-with-secret-store)の説明に従って HashiCorp Vault、Microsoft Active Directory、AWS Secrets Manager などに秘密情報を保存する場合は、対象システムに継続してアクセスできるか、接続情報を安全に保管してリカバリ後に接続できるかを事前に確認することを推奨します。 + +#### インフラストラクチャ構成 + +ACP の実行および運用に必要なインフラストラクチャ構成情報をバックアップし、リカバリできる必要があります。 +VM 上で Compose を使用して実行するか、Kubernetes 環境で実行するかなど、インフラストラクチャ構成によってバックアップおよびリカバリが必要な情報は異なります。 + +[システムアーキテクチャとネットワークアクセス制御](system-architecture-and-network-access-control)で説明している 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 のデータベースと実行設定は、同じ時点で取得した 1 つのバックアップセットとして管理することを推奨します。 + +1. 運用中の QueryPie コンテナイメージのバージョンと実行方法を確認します。 +2. QueryPie が使用する `querypie`、`querypie_snapshot`、`querypie_log` データベース、およびコンテナの環境変数、証明書、マウントファイルの場所を確認します。 +3. 外部 Secret Store とインフラストラクチャ構成のバックアップ状態を確認します。 +4. 可能な場合は、QueryPie への新規リクエストを遮断するかコンテナを停止して、一貫したバックアップ時点を確保します。サービスを停止できない場合は、MySQL が提供する一貫性のあるオンラインバックアップ、またはマネージドデータベースのスナップショット機能を使用します。 +5. バックアップ範囲で定義した `querypie`、`querypie_snapshot`、`querypie_log` データベースを、同じバックアップ処理または同じバックアップサイクルでバックアップします。 +6. コンテナの環境変数、証明書、Custom JDBC Driver、およびその他のマウントファイルをバックアップします。 +7. 外部 Secret Store とインフラストラクチャ構成情報を、お客様の運用ポリシーに従ってバックアップします。 +8. バックアップが完了したことを確認し、バックアップファイルの整合性を検証します。 +9. バックアップ日時と QueryPie コンテナイメージのバージョンを記録し、バックアップファイルを運用システムとは別の保存先に保管します。 + +#### mysqldump を使用したバックアップ例 + +次の例では、QueryPie ACP が使用する 3 つのデータベースを 1 つの SQL ファイルにバックアップします。 +山括弧で示した値は、実際の MySQL 接続情報に置き換えてください。 +```bash +mysqldump \ + --host="" \ + --port="" \ + --user="" \ + --password \ + --single-transaction \ + --hex-blob \ + --databases querypie querypie_snapshot querypie_log \ + > "querypie-backup-$(date +%Y%m%d-%H%M%S).sql" +``` + +`--password` オプションを使用すると、コマンド実行後にパスワード入力プロンプトが表示されます。 +パスワードがシェル履歴やプロセスリストに露出する可能性があるため、コマンドラインにパスワードを直接入力しないでください。 + +`--single-transaction` は、トランザクションをサポートするテーブルを一貫した時点でバックアップするために使用します。 +バックアップ中はスキーマ変更を実行しないことを推奨します。 + +バックアップアカウントには、3 つのデータベースを参照し、スキーマをダンプするために必要な権限が必要です。 +コマンドの終了ステータスと生成されたファイルのサイズを確認し、秘密情報と監査ログを含む SQL ファイルは機密情報として安全に保管してください。 + +### リカバリ手順 + +1. バックアップ時と同じ QueryPie コンテナイメージのバージョンと実行環境を準備します。 +2. MySQL と Redis を準備し、必要なネットワークアクセスを設定します。既存の Redis データはリカバリしません。 +3. データベースのリカバリが完了するまで QueryPie コンテナを起動しないでください。 +4. 同じバックアップセットから `querypie`、`querypie_snapshot`、`querypie_log` データベースをリカバリします。 +5. コンテナの環境変数、証明書、Custom JDBC Driver、およびその他のマウントファイルをリカバリします。 +6. `KEY_ENCRYPTION_KEY` には、バックアップ時と同じ値を必ず設定します。 +7. 外部 Secret Store を使用している場合は、リカバリした環境から対象システムにアクセスできることを確認します。 +8. Load Balancer、ファイアウォール、アクセス許可設定などのインフラストラクチャ構成をリカバリします。 +9. データベース接続情報とリカバリ状態を確認した後、QueryPie コンテナを起動します。 +10. QueryPie の起動状態とアプリケーションログを確認します。 + +サーバープロセスが再起動するかコンテナが置き換えられると、障害前に存在していたユーザーセッションは復元されません。 +ユーザーは再度ログインし、対象システムに再接続する必要があります。 + +#### mysql CLI を使用したリカバリ例 + +次の例では、前述の `mysqldump` コマンドで作成した SQL ファイルを MySQL にリカバリします。 +リカバリを開始する前に QueryPie コンテナが停止していることを確認し、山括弧で示した値とバックアップファイル名を実際の環境に合わせて変更してください。 +```bash +mysql \ + --host="" \ + --port="" \ + --user="" \ + --password \ + < "querypie-backup-YYYYMMDD-HHMMSS.sql" +``` + +`--password` オプションを使用すると、コマンド実行後にパスワード入力プロンプトが表示されます。 +パスワードがシェル履歴やプロセスリストに露出する可能性があるため、コマンドラインにパスワードを直接入力しないでください。 + +バックアップファイルは `--databases` オプションを使用して作成されているため、`querypie`、`querypie_snapshot`、`querypie_log` データベースの選択情報が含まれています。 +リカバリアカウントには、データベースとスキーマを作成し、データを復元するために必要な権限が必要です。 + +コマンドの終了ステータスを確認し、エラーがない場合にのみ QueryPie コンテナを起動してください。 +既存のデータベースにリカバリする場合は、事前に現在のデータを別途バックアップし、別の環境でリカバリ手順を検証してください。 + +### リカバリ後の確認 + +リカバリが完了したら、次の項目を確認します。 + +* QueryPie コンテナが正常に起動すること +* 管理者がログインできること +* ユーザーとグループが正常に表示されること +* アクセス対象の Database と Server が正常に表示されること +* ロール、権限、アクセス制御ポリシーが正常に表示されること +* 保存された Connection 情報を使用して対象システムに接続できること +* 既存のアクセスログ、実行ログ、監査ログの詳細を参照できること +* 新しいアクセスと操作が監査ログに正常に記録されること +* 外部 Secret Store を使用している場合、正常にアクセスできること +* Load Balancer とネットワークアクセス経路が正常に動作すること +* アプリケーションログにデータベース接続または初期化のエラーがないこと + +### 注意事項 + +* データベースのバックアップには、MySQL が提供する公式バックアップツールまたはマネージドデータベースサービスのバックアップ機能を使用してください。実行中の MySQL データファイルを通常のファイルコピーでバックアップしないでください。 +* `querypie`、`querypie_snapshot`、`querypie_log` は 1 つのバックアップセットとして管理し、リカバリ時も同じセットを使用してください。 +* `KEY_ENCRYPTION_KEY` はバックアップ時と同じ値を使用してください。異なる値を使用すると、暗号化された秘密情報を正常に復号できません。 +* データベースのリカバリが完了するまで QueryPie コンテナを起動しないでください。 +* 障害前に開かれていたユーザーセッションは復元されません。 +* バックアップファイルと設定情報は運用システムとは別の保存先に保管し、アクセス権限を制限してください。 +* バックアップが成功しただけでは、リカバリできることを保証できません。別の環境でリカバリ手順を定期的に検証することを推奨します。 +* バックアップ時と異なる QueryPie バージョンでリカバリとアップグレードを同時に実行しないことを推奨します。まずバックアップ時のバージョンでリカバリし、その後、別のアップグレード手順を実行してください。