Environment Variables for Advanced Setup - 10.3.x (KO)
소개
문서 변경일: 2025년 5월 12일
이 가이드는 QueryPie 의 설정 방법 가운데, 고급 수준의 설정 방법을 설명합니다. 이 문서에서는 다음의 두 가지 유형의 설정 방법을 구분하여 설명합니다.
compose-env 만 수정하여 설정할 수 있는 부분
docker-compose.yml 파일도 함께 수정해야하는 부분
compose-env 파일 수정사항
고객사마다 필요한 상황에 따라 아래와 같이 compose-env 파일을 수정해주어야 합니다.
공통 기능
Environment Variable Name | Default Value | Description |
---|---|---|
ENABLE_FILE_LOGGING |
|
|
API_JVM_HEAPSIZE |
| QueryPie API 컴포넌트의 Heap 메모리 설정 |
Redis 설정
Environment Variable Name | Default Value | Description |
---|---|---|
REDIS_DB |
| Redis Database Number. 0 부터 15 중 하나. 기본값은 |
REDIS_USE_SSL |
| QueryPie Redis 가 TLS 연결을 요구하는 경우, |
REDIS_USERNAME |
| Redis 가 Username 을 요구하는 경우, 설정합니다. |
REDIS_SERVER_CERT_FILE |
| Redis Server 의 TLS Certificate 설정에 사용한, Root CA 파일의 경로를 지정합니다. TLS 연결을 적용하는 경우, 이 값은 필수로 요구됩니다. |
REDIS_CLIENT_CERT_FILE |
| Client Certificate 파일의 경로를 지정합니다. mTLS 인증이 아니고, TLS 암호화만 적용하는 경우, 이 값을 빈 값으로 비워주세요. |
REDIS_CLIENT_KEY_FILE |
| Client Certificate 의 Private Key 파일 경로를 지정합니다. |
REDIS_CLIENT_KEY_PASSWORD |
| Client Certificate 파일을 열어보는데, Password 가 적용되어 있다면, 이 값을 설정합니다. |
Proxy 설정
Environment Variable Name | Default Value | Description |
---|---|---|
PROXY_PORT_START |
| DAC Agentless 로 사용할 Port 시작번호 (inclusive) |
PROXY_PORT_END |
| DAC Agentless 로 사용할 Port 끝번호 (inclusive) |
MySQL 연결 설정
Environment Variable Name | Default Value | Description |
---|---|---|
LOG_DB_HOST |
| Log DB로 사용할 DB host address |
LOG_DB_PORT |
| Log DB로 사용할 DB host port |
LOG_DB_USERNAME |
| Log DB로 사용할 DB의 username |
LOG_DB_PASSWORD |
| Log DB로 사용할 DB의 password |
LOG_DB_MAX_CONNECTION_SIZE |
| LOG DB 연결에 사용되는 최대 CONNECTION 수 |
ENG_DB_HOST |
| Snapshot DB로 사용할 DB host 주소 |
ENG_DB_PORT |
| Snapshot DB로 사용할 DB host port |
ENG_DB_USERNAME |
| Snapshot DB로 사용할 DB의 username |
ENG_DB_PASSWORD |
| Snapshot DB로 사용할 DB의 password |
QueryPie Tools 를 위한 MySQL 연결 설정
QueryPie Server Container 를 실행할 때 사용하는 DB 계정과, Tools 를 실행할 때 사용하는 DB 계정을, 서로 다른 계정으로 사용하려는 경우, 이 환경변수를 활용합니다.
QueryPie Server Container 실행시에는 Data Manipulation Language (SELECT, INSERT, UPDATE, DELETE) 권한만 부여할 수 있습니다. QueryPie Tools 실행할 때 일시적으로, Data Definition Language (CREATE, ALTER, DROP, TRUNCATE) 권한을 제한적으로 부여할 수 있습니다.
참조: [Tools] DB Admin 계정의 필수 권한
Environment Variable Name | Default Value | Description |
---|---|---|
DB_TOOLS_USERNAME |
| DDL 권한이 포함된 Meta DB Account Username |
DB_TOOLS_PASSWORD |
| DDL 권한이 포함된 Meta DB Account password |
LOG_DB_TOOLS_USERNAME |
| DDL 권한이 포함된 Log DB Account Username |
LOG_DB_TOOLS_PASSWORD |
| DDL 권한이 포함된 Log DB Account password |
ENG_DB_TOOLS_USERNAME |
| DDL 권한이 포함된 Snapshot DB Account Username |
ENG_DB_TOOLS_PASSWORD |
| DDL 권한이 포함된 Snapshot DB Account password |
Oven 저장소를 위한 연결 설정
Audit Log 를 효과적으로 저장하고 다룰 수 있는 Oven 컴포넌트를 활용하는 경우, 아래의 설정을 적용하여야 합니다.
Oven 컴포넌트의 활용에 대해서는, 기술지원 담당자에게 문의하시기 바랍니다.
Environment Variable Name | Default Value | Description |
---|---|---|
STORAGE_DB_HOST |
| OVEN 저장소 |
STORAGE_DB_PORT |
| OVEN 저장소 |
STORAGE_DB_CATALOG |
| OVEN 저장소 |
STORAGE_DB_USER |
| OVEN 저장소 |
STORAGE_DB_PASSWORD |
| OVEN 저장소 |
STORAGE_DB_MAX_CONNECTION_SIZE |
| OVEN 저장소 |
STORAGE_S3_ENABLED |
| OVEN 저장소에서 S3 사용 여부 |
STORAGE_S3_MODE |
| OVEN 저장소 S3 모드 |
STORAGE_S3_ENDPOINT |
| MinIO 엔드포인트 |
STORAGE_S3_BUCKET |
| S3 버킷 이름 |
STORAGE_S3_REGION |
| S3 리전 |
STORAGE_S3_CREDENTIAL_TYPE |
| S3 자격 증명 유형 |
STORAGE_S3_CREDENTIAL_ACCESS_KEY_ID |
| S3 접근 키 ID |
STORAGE_S3_CREDENTIAL_SECRET_ACCESS_KEY |
| S3 비밀 접근 키 |
STORAGE_S3_CREDENTIAL_SESSION_TOKEN |
| S3 세션 토큰 |
QueryPie 기능 변경을 위한 설정
특정 고객사의 보안정책, 요구사항에 따라, QueryPie 기능의 작동 방식을 변경하려는 경우, 다음의 환경변수를 설정할 수 있습니다.
Environment Variable Name | Default Value | Description |
---|---|---|
FF_DISABLE_DAC_PROXY_COMMENT |
| QueryPie 실행 시 붙이는 /* ApplicationName=QueryPie Proxy */ 류의 커멘트 제거 옵션 |
FF_DISABLE_DAC_INDIRECT_POLICY |
| 마스킹 정책이 적용된 컬럼을 WHERE 조건에 사용할 수 있도록 하는 환경 변수 |
JDBC Driver for AWS Aurora DB Clusters
QueryPie 가 Meta DB, Snapshot DB, Log DB 에 연결할 때 사용하는 JDBC Driver 를 변경하는 기능을 제공합니다. 이를 통해, AWS Aurora DB Clusters 를 사용하는 경우, 자동으로 Fail-Over 하는 기능을 사용할 수 있습니다.
AWS Aurora DB Clusters 를 사용하는 경우, compose-env
에 아래의 내용을 추가합니다.
### JDBC Driver for AWS Aurora DB Clusters
## The default value is org.mariadb.jdbc.Driver.
## For AWS Aurora DB clusters, QueryPie supports automatic fail-over
## when the driver is set to software.amazon.jdbc.Driver.
DB_DRIVER_CLASS=software.amazon.jdbc.Driver
ENG_DB_DRIVER_CLASS=software.amazon.jdbc.Driver
LOG_DB_DRIVER_CLASS=software.amazon.jdbc.Driver
DAC HTTPS Proxy 사용 설치 가이드 (Target DB: Athena, Trino)
Athena, Trino 를 위한 HTTP Proxy 에 대해, 유효한 공인 TLS 인증서를 적용할 수 있습니다. ( QueryPie 10.2.8 또는 이후의 개선된 버전에서는, docker-compose.yml
파일을 변경하지 않고, 설정을 진행합니다. )
첫번째 단계로, ./certs/
디렉토리 안에 인증서 파일을 넣습니다. 전달받은 인증서 파일의 이름이 localhost_querypie_com.pfx
인 경우, ./certs/localhost_querypie_com.pfx
의 경로가 되도록 저장합니다.
두번째 단계로, compose-env
에, 아래의 항목을 추가합니다.
### Enable TLS for HTTPS Proxy of Athena, Trino.
## You can install a valid TLS certificate for HTTPS Proxy of Athena or Trino.
## Please contact QueryPie Technical Support for more information.
PROXY_HTTPS_HOSTNAME=localhost.querypie.com
PROXY_HTTPS_CERT_PATH=/app/certs/localhost_querypie_com.pfx
PROXY_HTTPS_CERT_PASSWORD=
PROXY_HTTPS_CERT_PATH 의 값으로, /app/certs/
경로 이후에, 파일이름을 붙입니다. Docker Host 의 ./certs/
경로는 Container 내부에서 /app/certs/
경로에 Volume Mount 됩니다.
마지막으로, QueryPie Container 를 재시작합니다.
Environment Variable Name | Default Value | Description |
---|---|---|
PROXY_HTTPS_HOSTNAME |
| User Agent가 제공해주는 DB Connection의 hostname입니다. 특별한 이유가 없는 한 |
PROXY_HTTPS_CERT_PATH |
| 특별한 이유가 없는 한 |
PROXY_HTTPS_CERT_PASSWORD |
| 인증서 파일의 복호화 암호키를 입력합니다. QueryPie 로부터 공유받은 암호키를 사용합니다. |
HTTPS 서비스 제공을 위한 설정 가이드
다음의 문서를 참조하세요.
docker-compose.yml 파일 수정사항
아래에 설명된 시나리오에 따라, docker-compose.yml 와 compose-env 파일을 수정해줍니다.
classifier 사용 설치 가이드
(10.2.0 부터 지원)
아래와 같이 docker-compose.yml 파일에 classifier 컨테이너를 추가합니다.
classifier:
profiles:
- classifier
image: harbor.chequer.io/querypie/classifier:${VERSION:?ex. 10.2.0}
container_name: classifier
environment:
#- TORCH_NUM_THREAD=${TORCH_NUM_THREAD}
- CLASSIFIER_BATCH_SIZE=${CLASSIFIER_BATCH_SIZE:-20}
ports:
- 8081:8081
AIDD(classifier) 속도 성능 튜닝을 위해 다음과 같은 환경변수를 입력해 줄 수 있습니다.
Environment Variable Name | Default Value | Description |
---|---|---|
TORCH_NUM_THREAD |
| 분류기 내부에서 딥러닝이 실제로 사용하는 cpu thread 개수 |
CLASSIFIER_BATCH_SIZE |
| 분류기 내부에서 한번에 딥러닝 모델에 입력하는 데이터의 개수 |
querypie(app) 컨테이너에 주석처리 된 #- CLASSIFIER_URL=${CLASSIFIER_URL:-http://classifier:8081}
부분을 주석 해제하여 아래와 같이 만들어 줍니다.
...
# API
- EXTERNAL_URL=${QUERYPIE_WEB_URL}
- AWS_ACCOUNT_ID=${AWS_ACCOUNT_ID-}
- API_JVM_HEAPSIZE=${API_JVM_HEAPSIZE:-2g}
- CLASSIFIER_URL=${CLASSIFIER_URL:-http://classifier:8081}
...
TLS 연결을 요구하는 QueryPie MySQL 을 위한 설정
고객사 사례) 카카오엔터프라이즈
QueryPie MySQL 을 설정할 때, TLS 연결을 요구하는 MySQL Server 를 적용하는 경우, 해당 TLS 인증서 파일을 환경변수 설정을 통해 적용할 수 있습니다.
첫번째 단계로, mysql server 연결을 위한 Certificate 파일을
./certs/
디렉토리 안에 넣습니다. 각 파일을 다음의 이름으로 저장하는 것을 권장합니다.Root CA: mysql_server.crt
Client Certificate: mysql_client.pfx (PKCS12 형식의 인증서 파일)
두번째 단계로,
compose-env
환경변수 설정파일에, 아래의 환경변수를 설정합니다.세번째 단계로,
docker-compose.yml
파일에서, 추가한 환경변수를environment:
섹션이 추가합니다.services → app → environment 섹션, services → tools → environment 섹션, 두 곳에 모두 추가하여야 합니다.
설정을 완료한 후, QueryPie Server Container 를 재시작합니다.
Docker Host 에서 ./certs/
경로는 Container 내부에서는 /app/certs/
에 Mount 되도록 설정되어 있습니다. 환경변수의 파일 경로는 Container 내부의 파일 경로를 기준으로 설정하여야 합니다.
Environment Variable Name | Default Value | Description |
---|---|---|
DB_DRIVER_CLASS |
| 사용 가능한 값 : |
DB_SSL_MODE |
| 사용가능한 값 :
|
DB_SERVER_SSL_CERT |
| Root CA 파일의 경로를 지정합니다. mysql server 의 TLS 설정에 사용한 Root CA 인증서 파일을 의미합니다. |
DB_KEY_STORE |
| Client Certificate 파일의 경로를 지정합니다. 요구되는 파일의 형식은 PKCS12 입니다. |
DB_KEY_STORE_PASSWORD |
| Client Certificate 을 복호화하기 위한 Password 가 요구되는 경우, 입력합니다. |
Client Certificate 파일을 생성하는 절차, compose-env 와 docker-compose.yml 의 변경사항 등 상세한 설정 방법에 대해, 다음의 문서를 참조하세요: QueryPie MetaDB SSL 로 연결하기
Log DB, Snapshot DB 를 다른 DB Host 로 연결할 때, SSL 암호화를 사용하는 경우, 다음의 환경변수를 사용하면 됩니다.
DB_DRIVER_CLASS 관련: ENG_DB_DRIVER_CLASS, LOG_DB_DRIVER_CLASS
DB_SSL_MODE 관련: ENG_DB_SSL_MODE, LOG_DB_SSL_MODE
NOVA 사용 설치 가이드
QueryPie는 10.2.1 버전부터 NOVA(Network Outbound Virtual Access) 기능이 기본으로 같이 제공됩니다. Inbound Access 가 막혀 있는 분할된 네트워크 영역에 Nova Client 를 설치하여 실행하면, QueryPie Server 와 통신이 가능한 Reverse Proxy 환경을 구성할 수 있습니다. 이 Nova Client 가 Reverse Proxy 역할을 수행하여, QueryPie Server 는 분할된 네트워크 영역 내의 데이터베이스와 시스템에 접근할 수 있게 됩니다.
+-----------------------+ +---------------------+
| QueryPie | | Nova Client |
| +-------------+ | | |
| | Nova Server | 1. SSH Request | |
| | (9022) |<-------------------------| |
| | | | |
| | | 2. Create Tunnel | |
| | |==========================| |
| +-------------+ | | |
+-----------------------+ +---------------------+
NOVA Server 설치
아래와 같이 docker-compose.yml 내 querypie(app) 환경변수를 추가합니다.
... (Snipped) ...
app:
profiles:
- querypie
image: harbor.chequer.io/querypie/querypie:${VERSION:?ex. 10.2.1}
... (Snipped) ...
ports:
- ${NOVAS_AGENT_PORT}:${NOVAS_AGENT_PORT}
environment:
# NOVA Server
- NOVAS_AGENT_PORT=${NOVAS_AGENT_PORT:-9022}
- NOVAS_AGENT_TOKEN=${NOVAS_AGENT_TOKEN:?ex. e1134c60-d28f-4773-ade8-5001b412f778}
compose-env 에 환경변수를 추가합니다.
Environment Variable Name | Default Value | Description |
---|---|---|
NOVAS_AGENT_PORT |
| NOVA 서버의 엔드포인트 TCP 포트입니다. |
NOVAS_AGENT_TOKEN |
| NOVA 서버와 NOVA 클라이언트가 통신하기 위한 Access Token 입니다. |
NOVA Client 설치
아래와 같이 novac-compose.yml 내 novac 서비스의 설정 변경을 해주셔야합니다.
version: '3.8'
name: querypie-novac
services:
novac:
container_name: querypie-novac
profiles:
- novac
image: harbor.chequer.io/querypie/novac:10.2.1 # Version should be the same as version of QueryPie Server.
restart: always
environment:
- NOVAC_SERVER=example-novac-1.querypie.com:9022,example-novac-2.querypie.com:9022 # You should modify this line.
- NOVAC_TOKEN=e1134c60-d28f-4773-ade8-5001b412f778 # You should modify this line.
- NOVAC_NAME=example_novac1 # You should modify this line.
- NOVAC_TAGS=VPC=dev_infra;Env=Production # You should modify this line.
Environment Variable Name | Default Value | Description |
---|---|---|
NOVAC_SERVER |
| NOVAS 호스트 서버 정보 입니다. |
NOVAC_TOKEN |
| NOVA 서버 통신 시 사용하는 Access Token 입니다. |
NOVAC_NAME |
| NOVAS 로 전달할 NOVAC의 호스트 이름입니다. AWS 환경이라면 주로 NOVAC 가 설치되는 VPC 이름을 입력하시는걸 권장드립니다. |
NOVAC_TAGS |
| NOVAS 로 전달할 NOVAC의 태그 입니다. NOVAC 태그는 reverse tunnel 을 이용할 대상 server에 적용됩니다. |
아래는 novac 컨테이너 실행을 위한 샘플 명령어 입니다.
$ docker-compose -f novac-compose.yml --profile=novac up -d
AWS NLB PPv2 활성화 시 health check API 가이드
VPC Endpoint 를 활용한 VPC 간 통신 환경에서 출발지 IP 를 유지하고 싶은 경우, AWS NLB PPv2 를 사용할 수 있습니다.
이때 NLB PPv2 를 활성화할 경우, NLB가 TargetGroup으로 health check API 호출할 때, PPv2 방식으로 HTTP 요청을 보냅니다. (참조 - https://docs.aws.amazon.com/ko_kr/elasticloadbalancing/latest/network/edit-target-group-attributes.html#health-check-connections)
기존 제공되는 80포트의 /readyz
health check API 는 Proxy Protocol 을 지원하지 않아 health check 에 실패합니다. 이에 따라, 10080포트의 /readyz
API를 추가로 제공하여 PPv2 활성화 시, health check API 로 사용할 수 있도록 지원합니다.
10080포트의 health check API 는 docker-compose.yml 에서 기본값에서는 포트 바인딩 적용되어 있지 않습니다. 아래와 같이 docker-compose.yml 를 수정하여 10080포트의 포트 바인딩을 활성화합니다.
... (Snipped) ...
app:
profiles:
- querypie
image: harbor.chequer.io/querypie/querypie:${VERSION:?ex. 10.2.4}
... (Snipped) ...
ports:
... (Snipped) ...
# PPV2 Health Check Port
- 10080:10080
10080포트의 /readyz
는 Proxy Protocol 만 지원합니다.
NLB 가 Proxy Protocol 을 사용하지 않는 경우, 80포트의 /readyz
API를 Health Check Endpoint 로 사용하여야 합니다.