Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

구성 참고

이 페이지에서는 필요할 수 있는 모든 구성 키의 기본값과 의미를 설명합니다. 먼저 VM 설정 파일을, 이어서 Helm 차트 values를 다룹니다. 작업별 안내는 구성 가이드를 참조하십시오.

VM 설정 파일

Linux VM에서 커넥터는 clicklink clctl init이 작성한 /etc/clicklink/config.yaml을 읽습니다. --force를 지정하지 않으면 다시 실행해도 이 파일은 유지됩니다. 파일에서 생략된 키는 아래에 있는 컴파일된 기본값으로 폴백됩니다. 자격 증명은 이 파일에 저장되지 않습니다.

최상위 키

기본값 의미
pcm_infra_uuid init에서 생성 이 커넥터 배포의 고유 식별자로, 모든 upstream 요청에 포함됩니다. --force를 사용해 다시 실행해도 유지됩니다. 수정하지 마십시오.
cloud init에서 감지 이 호스트의 클라우드 제공업체 레이블입니다. 필수 항목이며, 비어 있으면 데몬이 시작되지 않습니다.
region init에서 감지 이 호스트의 리전 레이블입니다. 필수 항목이며, 비어 있으면 데몬이 시작되지 않습니다.
api upstream API 연결 블록입니다. api를 참조하십시오.
instances {} 이름별 ClickHouse 인스턴스 맵입니다. instances를 참조하십시오.
scraper 스크레이퍼 데몬 블록입니다. scraper를 참조하십시오.
troubleshooter 문제 해결 도구 데몬 블록입니다. troubleshooter를 참조하십시오.
observability 공유 로깅 및 포트 블록입니다. observability를 참조하십시오.

api

기본값 의미
api.endpoint 등록 번들에서 가져옴 조직의 커넥터 API 엔드포인트, https://<subdomain>.<connector domain>.
api.access_key_file /etc/clicklink/access-key (init이 생성) HMAC 액세스 키가 저장된 파일(모드 0600).
api.secret_key_file /etc/clicklink/secret-key (init이 생성) HMAC 시크릿 키가 저장된 파일(모드 0600).
api.tls.enabled true API 연결 시 mTLS 클라이언트 인증서를 제시합니다.
api.tls.cert_file /etc/clicklink/tls/client.crt mTLS 클라이언트 리프 인증서이며, 갱신 시 자동으로 재작성됩니다.
api.tls.key_file /etc/clicklink/tls/client.key mTLS 클라이언트 프라이빗 키.
api.tls.ca_file /etc/clicklink/tls/ca.crt 서버 검증을 위해 시스템 루트에 추가되는 추가 CA 체인입니다. init이 등록 번들의 체인을 여기에 설치합니다.
api.retry.max_retries 5 API 요청당 재시도 횟수.
api.retry.initial_delay 1s 첫 재시도 백오프 지연 시간.
api.retry.max_delay 30s 백오프 최대 지연 시간.
api.retry.jitter_factor 0.25 백오프 지연 시간에 적용되는 무작위 지터.

instances

instances.<name> 아래의 각 항목은 ClickHouse 네이티브 프로토콜 대상 하나를 설명합니다.

기본값 의미
host ClickHouse 네이티브 리스너의 호스트명 또는 IP 주소입니다.
port 네이티브 프로토콜 포트입니다(TLS 사용 시 일반적으로 9440, 평문 사용 시 9000).
database 커넥터 세션에서 기본으로 사용하는 데이터베이스입니다.
secure false 네이티브 연결에 TLS를 사용합니다.
max_open_conns unset 이 인스턴스에 열 수 있는 연결 수의 상한입니다.
max_idle_conns unset 이 인스턴스에 유지할 수 있는 유휴 풀 연결 수의 상한입니다.
namespace 인스턴스의 Kubernetes 네임스페이스이며, troubleshooter의 Kubernetes 읽기 범위를 지정하는 데 사용됩니다.
cluster default 분산 쿼리에 사용할 ClickHouse 클러스터 이름입니다.

scraper

기본값 의미
scraper.enabled false (inittrue를 기록함) scraper 데몬을 실행합니다.
scraper.labels.platform 내보내는 모든 메트릭에 추가되는 레이블입니다. scraper가 활성화된 경우 필수입니다.
scraper.labels.env 환경 레이블입니다. 예: production입니다. 필수입니다.
scraper.labels.region 리전 레이블입니다. 필수입니다.
scraper.scrape.interval 2m 각 인스턴스를 스크레이프하는 주기입니다.
scraper.scrape.timeout 30s 스크레이프별 쿼리 제한 시간입니다.
scraper.scrape.tables 아래 참조 인스턴스별로 스크레이프하는 시스템 테이블입니다. 기본값은 metric_log, asynchronous_metric_log, tables, warnings, server_settings이며, 기본적으로 원시 SQL 텍스트가 외부로 유출되지 않도록 query_log는 의도적으로 제외됩니다.
scraper.buffer.path /var/lib/clicklink/buffer API 엔드포인트에 연결할 수 없을 때 최소 한 번 이상 전송을 보장하기 위한 디스크 기반 스풀입니다.
scraper.buffer.retention 168h 스풀 데이터의 최대 보관 기간입니다.
scraper.buffer.max_size_mb 1024 스풀 크기 제한(MB)입니다.
scraper.sender.bandwidth_limit_mb 1.0 업로드 속도 제한(MB/s)입니다.
scraper.observability.health_port 8082 scraper 상태 확인 엔드포인트 포트입니다.
scraper.observability.metrics_port 9092 scraper 메트릭 포트입니다.
scraper.access_directory /etc/clicklink/access/scraper scraper의 인스턴스별 액세스 번들 루트 디렉터리입니다.

troubleshooter

기본값 의미
troubleshooter.enabled false (inittrue를 기록함) troubleshooter 데몬을 실행합니다.
troubleshooter.poll_interval 5s 세션 상태 폴링 주기입니다.
troubleshooter.command_timeout 60s 명령별 실행 타임아웃입니다.
troubleshooter.session_timeout 4h 기본 지원 세션 기간입니다.
troubleshooter.session_file_path /var/lib/clicklink/session.json clicklink clctl troubleshoot session 명령과 공유하는 세션 상태 파일입니다.
troubleshooter.access_directory /etc/clicklink/access/troubleshooter troubleshooter의 인스턴스별 액세스 번들 루트 디렉터리입니다.
troubleshooter.allowed_tables 기본 테이블 허용 목록 참조 troubleshooter가 SELECT할 수 있는 시스템 테이블입니다.
troubleshooter.max_open_conns 5 열려 있는 ClickHouse 연결 수의 상한입니다.
troubleshooter.max_idle_conns 5 유휴 연결 풀의 연결 수 상한입니다.
troubleshooter.redaction.workers 4 병렬 마스킹 worker 수입니다.
troubleshooter.redaction.patterns_file /etc/clicklink/redaction-patterns.yaml 고객이 편집할 수 있는 마스킹 패턴입니다. 파일이 존재하지만 유효하지 않으면 데몬이 시작되지 않습니다.
troubleshooter.redaction.metrics_per_pattern false 패턴별 일치 횟수 메트릭을 내보냅니다.
troubleshooter.redaction.metrics_per_pattern_cap 50 패턴별 메트릭에 포함할 서로 다른 패턴 이름 수의 상한입니다.
troubleshooter.audit_log.path /var/log/clicklink/troubleshoot-audit.log 허용되거나 차단된 모든 명령을 기록하는 추가 전용 NDJSON 감사 로그입니다.
troubleshooter.audit_log.max_size_mb 128 활성 로그 파일이 이 크기를 초과하면 순환합니다.
troubleshooter.audit_log.max_files 5 유지할 순환 로그 파일 수입니다.
troubleshooter.audit_log.max_age 168h 이보다 오래된 순환 로그 파일은 제거됩니다.
troubleshooter.gateway.enabled false 세션 Gateway(OIDC를 통한 지원 세션)를 제공합니다.
troubleshooter.gateway.listen_addr ":8443" (init가 기록함) Gateway 수신 주소입니다.
troubleshooter.gateway.audience clicklink-clctl (init가 기록함) 연산자 토큰에 필요한 audience 클레임입니다.
troubleshooter.gateway.required_hosted_domain "" 선택적 호스팅 도메인 클레임 검증 설정입니다. 도메인 외부의 토큰은 허용 목록을 조회하기 전에 거부됩니다.
troubleshooter.gateway.allowed_operators_file /etc/clicklink/allowed-operators.txt (init가 기록함) 줄바꿈으로 구분된 연산자 이메일 허용 목록입니다. 비어 있으면 모두 차단됩니다.
troubleshooter.gateway.rate_limit_per_minute 0 (비활성화됨) 연산자별 요청 속도 제한입니다.
troubleshooter.gateway.handler_timeout 설정되지 않음 서버 측 요청 타임아웃입니다.
troubleshooter.gateway.jwks_uri "" Google 이외 IdP(Identity Provider)를 위한 JWKS 엔드포인트입니다. 비어 있으면 Google의 엔드포인트를 사용합니다.
troubleshooter.gateway.issuer "" jwks_uri가 설정된 경우 고정할 issuer 클레임입니다.
troubleshooter.gateway.tls.enabled false (지원 세션이 활성화된 VM에서는 inittrue를 기록함) 인증서가 없을 때 데몬이 생성하는 자체 서명 인증서를 사용하여 TLS로 Gateway를 제공합니다. 연산자는 해당 인증서의 지문을 고정합니다.
troubleshooter.gateway.tls.cert_file /var/lib/clicklink/gateway/tls/server.crt Gateway 제공용 인증서입니다.
troubleshooter.gateway.tls.key_file /var/lib/clicklink/gateway/tls/server.key Gateway 제공용 키입니다.
troubleshooter.gateway.tls.self_signed_dns_names [] (init가 호스트를 미리 채움) 인증서가 없을 때 데몬이 자체 생성하는 자체 서명 인증서의 SAN입니다. IP 주소로 파싱되는 항목은 IP SAN이 됩니다.

관측성

기본값 의미
observability.enabled true 상태 확인 및 메트릭 엔드포인트를 제공합니다.
observability.log_level info 로그 레벨입니다.
observability.health_port 8080 공용 상태 확인 포트의 기준값입니다.
observability.metrics_port 9090 공용 메트릭 포트의 기준값입니다.

구성 요소별 observability 블록은 이 기본 설정을 덮어씁니다. scraper는 8082/9092를 사용하고, troubleshooter는 8084/9094를 사용하며, gateway는 활성화된 경우 8443에서 수신합니다.

기본 테이블 허용 목록

troubleshooter의 기본 allowed_tables Set은 차트의 기본 troubleshooter.allowedTables와 같습니다:

system.build_options    system.clusters       system.columns
system.databases        system.tables         system.parts
system.parts_columns    system.parts_summary  system.detached_parts
system.processes        system.merges         system.mutations
system.replicas         system.replication_queue
system.metrics          system.events         system.asynchronous_metrics
system.disks            system.storage_policies
system.settings         system.settings_profiles
system.settings_profile_elements
system.functions        system.formats        system.table_engines
system.users            system.roles          system.grants

Helm 차트 값

Kubernetes에서 커넥터는 clicklink-connector 차트의 values를 통해 구성됩니다. clicklink clctl init는 아래의 모든 항목이 채워진 clicklink-values.yaml 오버레이를 준비하며, --force를 지정하지 않는 한 다시 실행해도 이를 유지합니다. 표에는 차트의 기본값이 나열됩니다. 표준 워크로드 설정(resources, nodeSelector, tolerations, affinity, serviceAccount.annotations, env, imagePullSecrets)은 각 컴포넌트에 빈 기본값으로 제공되므로 표마다 반복해서 표시하지 않습니다.

cluster

기본값 의미
cluster.pcmInfraUuid "" (init에서 채움) 이 커넥터 배포의 고유 식별자입니다. 구성 요소가 하나라도 활성화된 경우 필수이며, 다시 실행해도 유지됩니다.
cluster.region "" (init에서 채움) 리전 레이블입니다. 필수입니다.
cluster.cloud "" (init에서 채움) 클라우드 제공업체 레이블입니다. 필수입니다.

image

기본값 의미
image.repository 게시된 차트에 사전 설정됨 Connector 이미지 리포지토리입니다. 게시된 차트는 공개 레지스트리 이미지(멀티 아키텍처, cosign 서명됨)를 가리킵니다. 경계 내 미러와 같이 재정의해야 할 때만 설정하십시오. 게시된 값은 helm show values로 확인할 수 있습니다.
image.tag "" (차트의 appVersion을 따르며, init은 CLI 버전을 고정함) 이미지 태그입니다.
image.pullPolicy IfNotPresent Kubernetes 이미지 가져오기 정책입니다.

api

기본값 의미
api.endpoint "" (init이 설정) 두 구성 요소에서 공유하는 조직 커넥터 API 엔드포인트입니다.
api.tls.enabled true API 연결 시 mTLS 클라이언트 인증서를 제시합니다.
api.tls.caFile "" (시스템 루트) 서버 검증을 위해 시스템 루트에 추가할 CA입니다. 엔드포인트가 private CA 인증서를 제공하는 경우 /etc/clicklink/secrets/mtls/ca.crt로 설정하거나 --api-private-ca 옵션으로 init을 다시 실행하십시오.

시크릿

차트는 사전에 생성된 시크릿을 사용하며, init는 설치 전에 이를 생성합니다.

기본값 의미
secrets.mtlsSecretName clicklink-mtls mTLS 클라이언트 키, 인증서 및 CA 체인을 담는 kubernetes.io/tls 시크릿입니다.
secrets.hmacSecretName clicklink-hmac 요청 서명용 access-keysecret-key를 담는 Opaque 시크릿입니다.
secrets.mtlsWriteback true 데몬이 자동 갱신된 mTLS 리프를 mTLS 시크릿에 다시 기록하도록 합니다. 정확한 이름으로 지정된 이 시크릿 하나에 대해서만 구성 요소 ServiceAccount에 update 권한을 부여합니다. 이를 설정하지 않으면 갱신된 인증서를 영구적으로 저장할 위치가 없습니다.

scraper

기본값 의미
scraper.enabled false (inittrue를 기록) scraper를 배포합니다.
scraper.replicaCount 1 scraper 레플리카 수입니다.
scraper.logLevel info 로그 레벨입니다.
scraper.ports.health 8082 상태 확인 엔드포인트 포트입니다.
scraper.ports.metrics 9092 메트릭 포트입니다.
scraper.instances {} ClickHouse 인스턴스 맵입니다. VM instances 필드와 동일한 형식을 사용합니다.
scraper.labels.platform, scraper.labels.env, scraper.labels.region "" 내보내는 모든 메트릭에 삽입되는 레이블입니다. scraper를 활성화하려면 세 가지를 모두 지정해야 하며, 그렇지 않으면 차트 렌더링 시 오류가 발생합니다.
scraper.config {} 위에 정의되지 않은 모든 scraper 구성 키를 그대로 전달합니다(스크레이프 인터벌, 버퍼, sender 등). VM scraper 블록과 동일한 스키마를 사용합니다.
scraper.bufferSizeLimit 2Gi scraper 스크래치 볼륨의 최대 크기입니다. scraper는 영구 디스크 상태를 저장하지 않습니다.
scraper.rbac.extraSecretNames [] scraper ServiceAccount가 get할 수 있는 추가 시크릿 이름입니다. 정확한 이름만 지정할 수 있습니다.
scraper.accessBundles {} 인스턴스 이름을 키로 하는 인스턴스별 액세스 번들입니다. 각 번들은 secretNameserviceAccountName을 포함합니다. /etc/clicklink/access/scraper/<instance>/에 마운트되며, clicklink clctl scraper access provision --target helm으로 생성됩니다.

troubleshooter

기본값 의미
troubleshooter.enabled false (inittrue를 기록함) troubleshooter(단일 레플리카 StatefulSet)를 배포합니다.
troubleshooter.logLevel info 로그 레벨입니다.
troubleshooter.ports.health 8084 상태 확인 엔드포인트 포트입니다.
troubleshooter.ports.metrics 9094 메트릭 포트입니다.
troubleshooter.instances {} scraper.instances와 동일한 구조의 ClickHouse 인스턴스 맵입니다.
troubleshooter.sessionTimeout 4h 기본 지원 세션 기간입니다.
troubleshooter.allowedTables 기본 테이블 허용 목록 troubleshooter의 ClickHouse 사용자가 SELECT할 수 있는 테이블입니다. 오버레이에서 수정해야 하는 보안 검토 대상이며, 여기에 나열된 항목과 관계없이 명령 검증기에는 하드코딩된 거부 목록(query_log, text_log)이 적용됩니다.
troubleshooter.auditLog.path /var/log/clicklink/troubleshoot-audit.log 감사 로그 위치입니다. 파드가 재스케줄링되어도 기록이 유지되도록 state 볼륨에 저장됩니다.
troubleshooter.auditLog.maxSizeMb 128 이 크기를 초과하면 순환합니다.
troubleshooter.auditLog.maxFiles 5 유지할 순환 파일 수입니다.
troubleshooter.auditLog.maxAge 168h 이보다 오래된 순환 파일은 프루닝됩니다.
troubleshooter.redaction.workers 4 병렬 민감 정보 마스킹 워커 수입니다.
troubleshooter.redaction.patternsConfigMap "" redaction-patterns.yaml 키에 사용자 정의 패턴이 포함된 ConfigMap의 이름입니다. 차트는 이를 /etc/clicklink/redaction-patterns.yaml에 마운트합니다. 비어 있으면 기본 제공 패턴만 적용됩니다.
troubleshooter.redaction.metricsPerPattern false 패턴별 일치 횟수 Counter 메트릭을 내보냅니다.
troubleshooter.redaction.metricsPerPatternCap 50 패턴별 메트릭에서 허용되는 고유 패턴 이름 수의 상한입니다.
troubleshooter.config {} 위에 정의되지 않은 troubleshooter 구성 키(폴링 주기, 명령 타임아웃, connection 상한 등)를 그대로 전달합니다.
troubleshooter.rbac.extraSecretNames [] troubleshooter ServiceAccount가 get할 수 있는 추가 시크릿 이름입니다. 정확한 이름만 지정할 수 있습니다.
troubleshooter.accessBundles {} scraper.accessBundles와 동일한 구조의 인스턴스별 액세스 번들이며, /etc/clicklink/access/troubleshooter/<instance>/에 마운트됩니다.

영속성

기본값 의미
persistence.enabled true PersistentVolumeClaim로 troubleshooter의 상태 디렉터리를 뒷받침하여 재시작 후에도 세션 상태와 감사 추적이 유지되도록 합니다.
persistence.storageClass "" (클러스터 기본값) 클레임에 사용할 StorageClass입니다. init--storage-class 또는 감지된 기본 StorageClass에서 값을 설정합니다.
persistence.size 5Gi 클레임 크기입니다.
persistence.accessModes [ReadWriteOnce] 클레임 액세스 모드입니다.

clctl.gateway

지원 세션을 위한 세션 gateway입니다.

기본값 의미
clctl.gateway.enabled false troubleshooter 내에서 세션 gateway를 제공합니다.
clctl.gateway.listenAddr ":8443" 파드 로컬 수신 주소입니다.
clctl.gateway.port 8443 troubleshooter Service 및 인그레스를 통해 노출되는 컨테이너 포트이며, listenAddr의 포트와 일치합니다.
clctl.gateway.audience clicklink-clctl 연산자 token에 필요한 audience 클레임입니다. 세션 클라이언트도 기본적으로 동일한 값을 사용하므로, 이 값을 변경할 때만 둘을 함께 조정하면 됩니다.
clctl.gateway.requiredHostedDomain "" 허용 목록 조회 전에 워크스페이스 외부 token을 거부하기 위해 gateway가 요구하는 선택적 hosted-domain 클레임입니다.
clctl.gateway.allowedOperators [] (닫힘) ConfigMap으로 렌더링되는 연산자 이메일 허용 목록입니다. 교체하려면 values를 변경한 후 helm upgrade를 실행합니다.
clctl.gateway.jwksUri "" Google 이외 IdP(Identity Provider)를 위한 JWKS 엔드포인트 재정의입니다. 비어 있으면 Google의 엔드포인트를 사용합니다.
clctl.gateway.issuer "" 고정할 issuer 클레임입니다. jwksUri를 설정하는 실제 배포에서는 필수입니다.
clctl.gateway.jwksEgressCIDRs [] 기본 거부 NetworkPolicy에서 JWKS 유효성 검사를 위해 gateway가 연결해야 하는 CIDR입니다. 비어 있으면 모든 token 검사가 차단됩니다.
clctl.gateway.ingressFromSelector {} gateway 포트에 대한 NetworkPolicy 인그레스 소스입니다. 비어 있으면 차트의 네임스페이스에 있는 모든 파드를 허용합니다. 인그레스를 사용할 때는 Ingress controller의 네임스페이스 레이블로 설정하십시오.
clctl.gateway.rateLimit.requestsPerMinute 30 연산자별 요청 속도 제한입니다.
clctl.gateway.ingress.enabled false gateway용 인그레스를 렌더링합니다. 비활성화하면 연산자는 kubectl port-forward로 gateway에 연결합니다. ingress controller나 cert-manager는 필요하지 않습니다.
clctl.gateway.ingress.className, hosts, tls, annotations "", [], [], {} 표준 Ingress 필드입니다. tlskubernetes.io/tls 시크릿을 참조합니다.

networkPolicy

기본값 의미
networkPolicy.enabled true 이그레스 허용 목록을 포함하는 기본 거부 NetworkPolicy를 생성합니다. 적용하려면 이를 지원하는 CNI가 필요합니다.
networkPolicy.allowEgressCIDRs [] 커넥터 API 엔드포인트가 위치한 CIDR입니다. 이를 지원하는 CNI에서는 이 값을 설정하기 전까지 커넥터의 이그레스가 허용되지 않습니다.
networkPolicy.allowEgressPorts [443] allowEgressCIDRs에 대해 열어 둘 포트입니다. 엔드포인트가 기본 포트가 아닌 포트에서 수신 대기하는 경우 재정의하십시오.
networkPolicy.clickhouseNamespaces [] kubernetes.io/metadata.name 레이블과 일치하는 ClickHouse 서비스의 네임스페이스입니다. 비어 있으면 클러스터 내 ClickHouse 접근은 허용되지 않습니다.
networkPolicy.metricsScrapeSelector {} 레이블을 사용해 메트릭 스크레이프 인그레스를 특정 Prometheus 네임스페이스로 제한합니다. 비어 있으면 차트의 네임스페이스에 있는 모든 파드에서 스크레이프를 허용합니다.
networkPolicy.kubeletProbeCIDRs [] 큐블릿 상태 probe 요청의 출발지 CIDR(노드 IP)입니다. 비어 있으면 대부분의 CNI에서 적용되는 큐블릿 예외와 동일하게 모든 출발지의 probe 인그레스를 허용합니다. 엄격한 기본 거부 환경에서는 명시적으로 설정하십시오.
networkPolicy.apiserverCIDRs [] Kubernetes API server CIDR입니다. 비어 있으면 API server 이그레스 규칙이 생성되지 않으며, 관리형 Kubernetes에서는 이를 설정할 때까지 데몬이 첫 번째 token 요청에 실패합니다.
Navigation