Environment Variables for Advanced Setup - 10.3.x (KO)
  • Completed
  • Environment Variables for Advanced Setup - 10.3.x (KO)

    소개

    문서 변경일: 2025년 5월 12일

    이 가이드는 QueryPie 의 설정 방법 가운데, 고급 수준의 설정 방법을 설명합니다. 이 문서에서는 다음의 두 가지 유형의 설정 방법을 구분하여 설명합니다.

    1. compose-env 만 수정하여 설정할 수 있는 부분

    2. docker-compose.yml 파일도 함께 수정해야하는 부분

    compose-env 파일 수정사항

    고객사마다 필요한 상황에 따라 아래와 같이 compose-env 파일을 수정해주어야 합니다.

    공통 기능

    Environment Variable Name

    Default Value

    Description

    Environment Variable Name

    Default Value

    Description

    ENABLE_FILE_LOGGING

    true

    /var/log/querypie 내 컴포넌트 별 로그 파일에 로그를 기록할 것인지 여부

    API_JVM_HEAPSIZE

    2g

    QueryPie API 컴포넌트의 Heap 메모리 설정

    Redis 설정

    Environment Variable Name

    Default Value

    Description

    Environment Variable Name

    Default Value

    Description

    REDIS_DB

    0

    Redis Database Number. 0 부터 15 중 하나. 기본값은 0.

    REDIS_USE_SSL

    false

    QueryPie Redis 가 TLS 연결을 요구하는 경우, true 로 설정합니다.
    QueryPie 는 TLS-Only, mTLS, 두 가지 방식의 TLS 연결 방식을 지원합니다.
    자세한 사항은 다음 문서를 참고하세요: QueryPie Redis with TLS Certificate (KO)

    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

    Environment Variable Name

    Default Value

    Description

    PROXY_PORT_START

    40000

    DAC Agentless 로 사용할 Port 시작번호 (inclusive)

    PROXY_PORT_END

    40030

    DAC Agentless 로 사용할 Port 끝번호 (inclusive)

     

    MySQL 연결 설정

    Environment Variable Name

    Default Value

    Description

    Environment Variable Name

    Default Value

    Description

    LOG_DB_HOST

    ${DB_HOST}

    Log DB로 사용할 DB host address

    LOG_DB_PORT

    ${DB_PORT}

    Log DB로 사용할 DB host port

    LOG_DB_USERNAME

    ${DB_USERNAME}

    Log DB로 사용할 DB의 username

    LOG_DB_PASSWORD

    ${DB_PASSWORD}

    Log DB로 사용할 DB의 password

    LOG_DB_MAX_CONNECTION_SIZE

    ${DB_MAX_CONNECTION_SIZE:-20}

    LOG DB 연결에 사용되는 최대 CONNECTION 수

    ENG_DB_HOST

    ${DB_HOST}

    Snapshot DB로 사용할 DB host 주소

    ENG_DB_PORT

    ${DB_PORT}

    Snapshot DB로 사용할 DB host port

    ENG_DB_USERNAME

    ${DB_USERNAME}

    Snapshot DB로 사용할 DB의 username

    ENG_DB_PASSWORD

    ${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

    Environment Variable Name

    Default Value

    Description

    DB_TOOLS_USERNAME

    ${DB_USERNAME}

    DDL 권한이 포함된 Meta DB Account Username

    DB_TOOLS_PASSWORD

    ${DB_PASSWORD}

    DDL 권한이 포함된 Meta DB Account password

    LOG_DB_TOOLS_USERNAME

    ${DB_USERNAME}

    DDL 권한이 포함된 Log DB Account Username

    LOG_DB_TOOLS_PASSWORD

    ${DB_PASSWORD}

    DDL 권한이 포함된 Log DB Account password

    ENG_DB_TOOLS_USERNAME

    ${DB_USERNAME}

    DDL 권한이 포함된 Snapshot DB Account Username

    ENG_DB_TOOLS_PASSWORD

    ${DB_PASSWORD}

    DDL 권한이 포함된 Snapshot DB Account password

    Oven 저장소를 위한 연결 설정

    Audit Log 를 효과적으로 저장하고 다룰 수 있는 Oven 컴포넌트를 활용하는 경우, 아래의 설정을 적용하여야 합니다.

    Oven 컴포넌트의 활용에 대해서는, 기술지원 담당자에게 문의하시기 바랍니다.

    Environment Variable Name

    Default Value

    Description

    Environment Variable Name

    Default Value

    Description

    STORAGE_DB_HOST

    ${ENG_DB_HOST}

    OVEN 저장소

    STORAGE_DB_PORT

    ${ENG_DB_PORT}

    OVEN 저장소

    STORAGE_DB_CATALOG

    ${ENG_DB_CATALOG}

    OVEN 저장소

    STORAGE_DB_USER

    ${ENG_DB_USERNAME}

    OVEN 저장소

    STORAGE_DB_PASSWORD

    ${ENG_DB_PASSWORD}

    OVEN 저장소

    STORAGE_DB_MAX_CONNECTION_SIZE

    ${DB_MAX_CONNECTION_SIZE}

    OVEN 저장소

    STORAGE_S3_ENABLED

    false

    OVEN 저장소에서 S3 사용 여부

    STORAGE_S3_MODE

    aws

    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

    Environment Variable Name

    Default Value

    Description

    FF_DISABLE_DAC_PROXY_COMMENT

    false

    QueryPie 실행 시 붙이는 /* ApplicationName=QueryPie Proxy */ 류의 커멘트 제거 옵션

    FF_DISABLE_DAC_INDIRECT_POLICY

    false

    마스킹 정책이 적용된 컬럼을 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

    Environment Variable Name

    Default Value

    Description

    PROXY_HTTPS_HOSTNAME

     

    User Agent가 제공해주는 DB Connection의 hostname입니다. 특별한 이유가 없는 한 localhost.querypie.com 을 사용합니다.

    PROXY_HTTPS_CERT_PATH

     

    특별한 이유가 없는 한 /app/certs/localhost_querypie_com.pfx 을 사용합니다.

    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

    Environment Variable Name

    Default Value

    Description

    TORCH_NUM_THREAD

    (자동 감지하여 결정)

    분류기 내부에서 딥러닝이 실제로 사용하는 cpu thread 개수

    CLASSIFIER_BATCH_SIZE

    20

    분류기 내부에서 한번에 딥러닝 모델에 입력하는 데이터의 개수

    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

    Environment Variable Name

    Default Value

    Description

    DB_DRIVER_CLASS

    org.mariadb.jdbc.Driver

    사용 가능한 값 : org.mariadb.jdbc.Driver, software.amazon.jdbc.Driver

    DB_SSL_MODE

     

    사용가능한 값 : DISABLED, TRUST, VERIFY_CA, VERIFY_FULL

    DISABLED: 암호화되지 않은 연결을 사용합니다.
    VERIFY_CA: Root CA 를 이용하여, Server 의 TLS 인증서 유효성을 검사합니다.

    DB_SERVER_SSL_CERT

     

    Root CA 파일의 경로를 지정합니다. mysql server 의 TLS 설정에 사용한 Root CA 인증서 파일을 의미합니다.
    file:/app/certs/ 로 시작하는 경로를 갖게 됩니다.

    DB_KEY_STORE

     

    Client Certificate 파일의 경로를 지정합니다. 요구되는 파일의 형식은 PKCS12 입니다.
    file:/app/certs/ 로 시작하는 경로를 갖게 됩니다.
    Client Certificate 이 요구되지 않는 경우, 빈 값으로 둡니다.

    DB_KEY_STORE_PASSWORD

     

    Client Certificate 을 복호화하기 위한 Password 가 요구되는 경우, 입력합니다.
    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

    Environment Variable Name

    Default Value

    Description

    NOVAS_AGENT_PORT

    9022

    NOVA 서버의 엔드포인트 TCP 포트입니다.

    NOVAS_AGENT_TOKEN

     

    NOVA 서버와 NOVA 클라이언트가 통신하기 위한 Access Token 입니다.
    ,를 제외한 랜덤 문자열. e.g. e1134c60-d28f-4773-ade8-5001b412f778

     

    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

    Environment Variable Name

    Default Value

    Description

    NOVAC_SERVER

     

    NOVAS 호스트 서버 정보 입니다. , 구분으로 여러개의 NOVAS 호스트를 입력할 수 있습니다.
    예) novas-1.dev.querypie.com:9022,novas-2.dev.querypie.com:9022

    NOVAC_TOKEN

     

    NOVA 서버 통신 시 사용하는 Access Token 입니다.
    NOVAS의 NOVAS_AGENT_TOKEN 와 달리 한 개 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 로 사용하여야 합니다.