VM 설정 파일
Linux VM에서 커넥터는/etc/clicklink/config.yaml을 읽습니다. clicklink clctl init이 이 파일을 작성하며, --force를 지정하지 않으면 다시 실행해도 이 파일은 유지됩니다. 파일에서 생략된 키는 아래에 있는 컴파일된 기본값으로 폴백됩니다. init은 이 파일에 자격 증명을 기록하지 않습니다. HMAC 키는 *_file 경로에, 클라이언트 인증서는 /etc/clicklink/tls 아래에 저장됩니다.
최상위 키
| 키 | 기본값 | 의미 |
|---|---|---|
pcm_infra_uuid | init에서 생성 | 이 커넥터 배포의 고유 식별자로, 모든 upstream 요청에 포함됩니다. --force를 사용해 다시 실행해도 유지됩니다. 수정하지 마십시오. |
cloud | init에서 감지 | 이 호스트의 클라우드 제공업체 레이블입니다. 필수 항목이며, 비어 있으면 데몬이 시작되지 않습니다. |
region | init에서 감지 | 이 호스트의 리전 레이블입니다. 필수 항목이며, 비어 있으면 데몬이 시작되지 않습니다. |
namespace_prefix | ns- | 관리형 서비스가 존재하는 Kubernetes 네임스페이스의 접두사입니다(<prefix><service>). 모든 데몬이 이 값을 기반으로 네임스페이스를 도출합니다. |
report_infra_meta | true | 하트비트마다 관리형 클러스터의 이름, 리전, 계정을 ClickHouse Cloud에 보고합니다. 차트의 cluster.reportInfraMeta에 해당하는 VM 설정입니다. |
token_renew.sweep_interval | 10m | 실행기와 scraper가 액세스 번들 ServiceAccount 토큰의 갱신 여부를 확인하는 주기입니다. |
token_renew.requested_ttl | 24h | 갱신 시 요청하는 토큰 수명입니다. API server가 이보다 낮은 값으로 제한할 수 있습니다. |
api | upstream API 연결 블록입니다. api를 참조하십시오. | |
scraper | scraper 데몬 블록입니다. scraper를 참조하십시오. | |
troubleshooter | 문제 해결 도구 데몬 블록입니다. troubleshooter를 참조하십시오. | |
executor | 실행기 데몬 블록(관리형 모드)입니다. executor를 참조하십시오. | |
observability | 공유 로깅 및 포트 블록입니다. observability를 참조하십시오. |
instances: 섹션을 무시합니다. 인스턴스는 인스턴스 레지스트리에 존재합니다.
api
| 키 | 기본값 | 의미 |
|---|---|---|
api.endpoint | 등록 번들에서 가져옴 | 커넥터 엔드포인트, 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.access_key, api.secret_key | 설정 안 됨 | 인라인 HMAC 키이며, 개발 용도로만 사용합니다. init은 이 값을 기록하지 않습니다. 이 값을 담은 파일에는 키 파일과 동일한 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 | 백오프 지연 시간에 적용되는 무작위 지터. |
인스턴스 레지스트리
인스턴스는/var/lib/clicklink/instances.yaml에 저장되며, 이름을 키로 하는 최상위 instances: 맵 형태입니다. init이 이 파일을 초기화하고 실행기가 이를 유지 관리합니다. scraper가 이 파일을 watch하므로 편집 내용은 재시작 없이 적용됩니다. 각 항목은 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 (init가 true를 기록함) | scraper 데몬을 실행합니다. |
scraper.labels.platform | 내보내는 모든 메트릭에 추가되는 레이블입니다. scraper가 활성화된 경우 필수입니다. | |
scraper.labels.env | 환경 레이블입니다. 예: production입니다. 필수입니다. | |
scraper.labels.region | 리전 레이블입니다. 필수입니다. | |
scraper.scrape.interval | 2m | 각 인스턴스를 스크레이프하는 주기입니다. |
scraper.scrape.timeout | 30s | 스크레이프별 쿼리 제한 시간입니다. interval보다 짧아야 합니다. |
scraper.scrape.max_scrape_window | 30m | 커서가 저장되어 있지 않을 때 첫 스크레이프가 과거로 얼마나 거슬러 올라갈지입니다. |
scraper.scrape.grace_period | 35s | 각 스크레이프 윈도우가 현재 시각보다 얼마나 이전에 끝나는지로, 늦게 기록된 행이 누락되지 않도록 합니다. |
scraper.scrape.tables | 아래 참조 | 인스턴스별로 스크레이프하는 시스템 테이블입니다. 기본값은 metric_log, asynchronous_metric_log, tables, warnings, server_settings입니다. query_log는 의도적으로 제외되므로, 기본적으로 원시 SQL 텍스트가 외부로 유출되지 않습니다. |
scraper.buffer.path | /var/lib/clicklink/buffer | 커넥터 엔드포인트에 연결할 수 없을 때 최소 한 번 이상 전송을 보장하기 위한 디스크 기반 스풀입니다. |
scraper.buffer.retention | 168h | 스풀 데이터의 최대 보관 기간입니다. |
scraper.buffer.max_size_mb | 1024 | 스풀 크기 제한(MB)입니다. |
scraper.buffer.max_segments | 0 (무제한) | 디스크에 저장되는 스풀 세그먼트 파일 수 제한입니다. |
scraper.sender.bandwidth_limit_mb | 1.0 | 업로드 속도 제한(MB/s)입니다. |
scraper.instance_sync.interval | 0 (30s) | scraper가 등록된 각 인스턴스의 ClickHouseCluster 상태를 ClickHouse Cloud에 보고하는 주기입니다. |
scraper.backup_sync.interval | 0 (30s) | scraper가 backup 상태를 ClickHouse Cloud에 보고하는 주기입니다. |
scraper.observability.health_port | 8082 | scraper 상태 확인 및 메트릭 포트입니다. |
scraper.access_directory | /etc/clicklink/access/scraper | scraper의 인스턴스별 액세스 번들 루트 디렉터리입니다. |
troubleshooter
| 키 | 기본값 | 의미 |
|---|---|---|
troubleshooter.enabled | false (init가 true를 기록함) | 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할 수 있는 시스템 테이블입니다. 항목은 schema.table 형식이어야 합니다. query_log 또는 text_log가 나열되어 있으면 데몬이 시작되지 않습니다. |
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 | 없음 (init가 ":8443"을 기록함) | Gateway 수신 주소입니다. Gateway가 활성화된 경우 필수입니다. |
troubleshooter.gateway.audience | 없음 (init가 clicklink-clctl을 기록함) | 연산자 토큰에 필요한 audience 클레임입니다. Gateway가 활성화된 경우 필수입니다. |
troubleshooter.gateway.required_hosted_domain | "" | 선택적 호스팅 도메인 클레임 검증 설정입니다. Gateway는 도메인 외부의 토큰을 허용 목록을 조회하기 전에 거부합니다. |
troubleshooter.gateway.allowed_operators_file | /etc/clicklink/allowed-operators.txt (init가 기록함) | 줄바꿈으로 구분된 연산자 이메일 허용 목록입니다. 비어 있으면 모두 차단됩니다. Gateway가 활성화된 경우 필수이며, 이 파일이 없으면 데몬이 시작되지 않습니다. |
troubleshooter.gateway.require_verified_email | true | 연산자 토큰에 email_verified 클레임을 요구합니다. false는 jwks_uri와 issuer가 설정된 경우에만 적용됩니다. |
troubleshooter.gateway.rate_limit_per_minute | 0 (비활성화됨) | 연산자별 요청 속도 제한입니다. |
troubleshooter.gateway.handler_timeout | 15s | 서버 측 요청 타임아웃입니다. |
troubleshooter.gateway.jwks_uri | "" | Google 이외 IdP(Identity Provider)를 위한 JWKS 엔드포인트입니다. 비어 있으면 Google의 엔드포인트를 사용합니다. |
troubleshooter.gateway.issuer | "" | jwks_uri가 설정된 경우 고정할 issuer 클레임입니다. |
troubleshooter.gateway.tls.enabled | false (지원 세션이 활성화된 VM에서는 init가 true를 기록함) | 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.ca_file | "" | 연산자 클라이언트 인증서가 체인으로 연결되어야 하는 CA입니다. 설정하면 OIDC bearer에 더해 mTLS가 필요합니다. |
troubleshooter.gateway.tls.self_signed_dns_names | [] (init가 호스트를 미리 채움) | 자체 서명 인증서의 SAN입니다. IP 주소로 파싱되는 항목은 IP SAN이 됩니다. |
executor
실행기는 관리형 모드로 동작합니다.init --managed는 enabled: true와 cluster 아이덴티티를 기록하며, 나머지 항목은 기본값으로 폴백됩니다.
| Key | Default | 의미 |
|---|---|---|
executor.enabled | false (init --managed은 true를 기록) | 실행기 데몬을 실행합니다. |
executor.cluster.name | init이 기록 | 이 실행기가 관리하는 단일 EKS 클러스터의 이름입니다. 실행기가 활성화된 경우 필수입니다. |
executor.cluster.region | init이 기록 | 해당 클러스터의 AWS 리전입니다. 필수입니다. |
executor.cluster.account_id | init이 기록 | 해당 클러스터의 AWS account입니다. 필수입니다. |
executor.cluster.kubeconfig_path | 미설정 | 실행기가 인증에 사용하는 kubeconfig입니다. 설정하지 않으면 모든 service 명령어가 /etc/clicklink/access/executor 아래의 액세스 번들을 사용해 실행됩니다. |
executor.cluster.in_cluster | false | kubeconfig 대신 파드 자체의 ServiceAccount로 인증합니다. Kubernetes 설치 방식의 형태이며, kubeconfig_path와 함께 사용할 수 없습니다. |
executor.cluster.delete_instance_data.enabled | false | clicklink clctl executor teardown이 --delete-data 없이도 Retired된 service의 데이터를 삭제할지 여부입니다. 실행기 데몬 자체는 어떤 데이터도 삭제하지 않습니다. |
executor.target_cluster | executor.cluster.name | 인바운드 명령어가 dispatch되는 클러스터입니다. 설정하지 않은 상태로 두십시오. 다른 값을 지정하면 시작 시 치명적 오류가 발생합니다. |
executor.poll_interval | 5m | 폴링 주기입니다. 양수여야 합니다. |
executor.sync_interval | 30s | 클러스터에서 service 상태를 갱신하는 주기입니다. 양수여야 합니다. |
executor.stop_wait_timeout | 8m | 삭제 작업이 재시도하기 전에 서버가 중지되기를 기다리는 시간입니다. |
executor.create_retry_horizon | 30m | 마지막 Progress 보고 시점부터 계산하여 CREATE 작업을 재시도하는 시간입니다. |
executor.delete_retry_horizon | 2h | 마지막 Progress 보고 시점부터 계산하여 삭제 작업을 재시도하는 시간입니다. |
executor.db_path | /var/lib/clicklink/executor.db | 로컬 명령어 데이터베이스입니다. |
executor.api_port | 9999 | 로컬 API 포트이며, 루프백에만 바인딩됩니다. |
executor.observability.health_port | 8086 | 실행기 health 및 메트릭 포트입니다. |
executor.cluster는 단일 매핑으로, 실행기당 클러스터 하나를 의미합니다. 로더는 cluster: 매핑이 없는 legacy 방식의 단일 항목 clusters: 목록을 cluster로 통합합니다. 실행기가 활성화된 상태에서 항목이 둘 이상인 목록이거나 cluster: 키와 함께 지정된 목록은 거부됩니다.
관측성
| 키 | 기본값 | 의미 |
|---|---|---|
observability.enabled | true | 상태 확인 및 메트릭 엔드포인트를 제공합니다. |
observability.log_level | info | 로그 레벨입니다. |
observability.health_port | 8080 | 공용 상태 확인 포트의 기준값입니다. |
/livez(JSON 상태 body), /readyz, /healthz, /metrics를 제공하며, 별도의 메트릭 포트는 없습니다. 구성 요소별 observability 블록은 이 기본 설정을 덮어씁니다. scraper는 8082, troubleshooter는 8084, executor는 8086을 사용하며, gateway는 활성화된 경우 8443에서 수신합니다. 이전 구성의 metrics_port 키는 여전히 로드되지만 아무것도 바인딩하지 않습니다.
기본 테이블 허용 목록
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)은 각 컴포넌트에 빈 기본값으로 제공되므로 표마다 반복해서 표시하지 않습니다.
최상위 키
| Key | 기본값 | 의미 |
|---|---|---|
imagePullSecrets | [] | 모든 구성 요소가 공유하는 image pull 시크릿입니다. |
instances | {} | 직접 운영하는 ClickHouse 인스턴스의 레지스트리로, VM 인스턴스 레지스트리와 필드가 동일하며 clicklink-instance-registry ConfigMap으로 렌더링됩니다. executor.enabled가 true이면 반드시 비어 있어야 하며, 그렇지 않으면 렌더링에 실패합니다. |
podSecurityContext | non-root, uid 65532, RuntimeDefault seccomp | 모든 구성 요소가 공유하는 파드 보안 컨텍스트입니다. |
securityContext | privilege escalation 없음, 읽기 전용 루트 파일 시스템, 모든 capability 제거 | 모든 구성 요소가 공유하는 컨테이너 보안 컨텍스트입니다. |
serviceMonitor.enabled | false | 구성 요소 Service에 대한 Prometheus Operator ServiceMonitor를 렌더링합니다. namespace, interval(30s), scrapeTimeout(10s), labels로 세부 설정을 지정합니다. |
externalSecrets.enabled | false | 미리 생성한 시크릿 대신 External 시크릿 Operator를 통해 mTLS, HMAC, access bundle 시크릿을 구체화합니다. 원격 스토어와 키는 secretStoreRef, refreshInterval(1h), mtlsRemoteKey, hmacRemoteKey, accessBundles로 지정합니다. |
cluster
| 키 | 기본값 | 의미 |
|---|---|---|
cluster.pcmInfraUuid | "" (init에서 채움) | 이 커넥터 배포의 고유 식별자입니다. 구성 요소가 하나라도 활성화된 경우 필수이며, 다시 실행해도 유지됩니다. |
cluster.region | "" (init에서 채움) | 리전 레이블입니다. 필수입니다. |
cluster.cloud | "" (init에서 채움) | 클라우드 제공업체 레이블입니다. 필수입니다. |
cluster.namespacePrefix | ns- | 관리형 서비스가 위치하는 Kubernetes 네임스페이스의 접두사입니다(<prefix><service>). |
cluster.reportInfraMeta | true | 문제 분류를 위해 하트비트마다 관리형 클러스터의 이름, 리전, 계정을 ClickHouse Cloud에 보고합니다. 사용하지 않으려면 false로 설정하십시오. |
image
| 키 | 기본값 | 의미 |
|---|---|---|
image.repository | 게시된 차트에 사전 설정됨 | Connector 이미지 리포지토리입니다. 게시된 차트는 공개 레지스트리 이미지(멀티 아키텍처, cosign 서명됨)를 가리킵니다. 경계 내 미러와 같이 재정의해야 할 때만 설정하십시오. 게시된 값은 helm show values로 확인할 수 있습니다. |
image.tag | "" (차트의 appVersion을 따르며, init은 CLI 버전을 고정함) | 이미지 태그입니다. |
image.pullPolicy | IfNotPresent | Kubernetes 이미지 가져오기 정책입니다. |
api
| 키 | 기본값 | 의미 |
|---|---|---|
api.endpoint | "" (init이 설정) | 모든 구성 요소에서 공유하는 커넥터 엔드포인트입니다. |
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-key 및 secret-key를 담는 Opaque 시크릿입니다. |
secrets.mtlsWriteback | true | 데몬이 자동 갱신된 mTLS 리프를 mTLS 시크릿에 다시 기록하도록 합니다. 정확한 이름으로 지정된 이 시크릿 하나에 대해서만 구성 요소 ServiceAccount에 update 권한을 부여합니다. 이를 설정하지 않으면 갱신된 인증서를 영구적으로 저장할 위치가 없습니다. externalSecrets.enabled가 true인 경우 무시됩니다. |
scraper
| 키 | 기본값 | 의미 |
|---|---|---|
scraper.enabled | false (init가 true를 기록) | scraper를 배포합니다. |
scraper.replicaCount | 1 | scraper 레플리카 수입니다. |
scraper.logLevel | info | 로그 레벨입니다. |
scraper.ports.health | 8082 | 상태 확인 및 메트릭 포트입니다. |
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 | {} | 인스턴스 이름을 키로 하는 인스턴스별 액세스 번들입니다. 각 번들은 secretName과 serviceAccountName을 포함합니다. /etc/clicklink/access/scraper/<instance>/에 마운트되며, clicklink clctl scraper access provision --target helm으로 생성됩니다. |
troubleshooter
| 키 | 기본값 | 의미 |
|---|---|---|
troubleshooter.enabled | false (init가 true를 기록함) | troubleshooter(단일 레플리카 StatefulSet)를 배포합니다. |
troubleshooter.logLevel | info | 로그 레벨입니다. |
troubleshooter.ports.health | 8084 | 상태 확인 및 메트릭 포트입니다. |
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>/에 마운트됩니다. |
executor
관리형 모드용 실행기로, PersistentVolumeClaim을 사용하는 단일 레플리카 Deployment입니다.init --managed는 클러스터 아이덴티티를 채워 넣고 활성화된 상태로 준비합니다.
| Key | 기본값 | 의미 |
|---|---|---|
executor.enabled | false (init --managed는 true로 기록) | 실행기를 배포합니다. |
executor.logLevel | info | 로그 레벨입니다. |
executor.pollInterval | 30s | 폴링 주기입니다. |
executor.syncInterval | 30s | 클러스터에서 서비스 상태를 갱신하는 주기입니다. |
executor.apiPort | 9999 | 로컬 API 포트입니다. 파드 내에서 127.0.0.1에 바인딩되며 Service를 통해 노출되지 않으므로 kubectl port-forward로 접근하십시오. |
executor.ports.health | 8086 | 상태 확인 및 메트릭 포트입니다. |
executor.cluster.name | "" (init이 채움) | 이 실행기가 관리하는 단일 EKS 클러스터의 이름입니다. 실행기가 활성화된 경우 필수입니다. |
executor.cluster.region | "" (init이 채움) | 해당 클러스터의 AWS 리전입니다. 필수입니다. |
executor.cluster.accountId | "" (init이 채움) | 해당 클러스터의 AWS 계정입니다. 필수이며, snake_case 표기인 account_id도 허용됩니다. |
executor.cluster.inCluster | false (init은 true로 기록) | 파드의 ServiceAccount로 인증합니다. 이는 Kubernetes 설치 형태에 해당하며, 파드 내에는 액세스 번들이 존재하지 않습니다. |
executor.cluster.delete_instance_data.enabled | false | clicklink clctl executor teardown이 --delete-data 없이도 폐기된 서비스의 데이터를 삭제할지 여부입니다. init은 이 값을 설정하지 않은 채로 둡니다. 그 밖의 클러스터별 키는 바이너리의 snake_case 표기 그대로 전달됩니다. |
executor.targetCluster | "" (cluster.name에서 파생) | 인바운드 명령어가 전달되는 클러스터입니다. 설정하지 않은 채로 두십시오. cluster.name과 일치하지 않는 값은 렌더링 시 실패합니다. |
executor.config | {} | 위에 정의되지 않은 모든 executor 구성 키에 대한 패스스루입니다. 예를 들어 VM executor 블록의 재시도 기한 등이 해당됩니다. |
executor.platformBundleSecret | clicklink-platform-bundle | 플랫폼 승인 번들을 보관하는 시크릿으로, /etc/clicklink/access/executor/_platform에 읽기 전용으로 마운트됩니다. clicklink clctl platform approve --secret-namespace가 이를 기록합니다. 이 마운트는 선택 사항이므로 첫 승인 이전에도 파드가 시작됩니다. 비워 두면 마운트가 비활성화됩니다. |
executor.serviceAccount.create | false | 차트가 실행기용 ServiceAccount를 생성할지 여부입니다. 기본값은 비활성화입니다. init --managed가 고정된 이름에 대해 실행기의 RBAC를 별도로 부여하고, 차트는 여기에 바인딩합니다. |
executor.serviceAccount.name | pcm-executor | 실행기가 사용하는 ServiceAccount입니다. create가 false일 때 필수입니다. |
executor.persistence.enabled | true | /var/lib/clicklink(명령어 데이터베이스 및 인스턴스 레지스트리)를 PersistentVolumeClaim으로 뒷받침합니다. |
executor.persistence.storageClass | "" (클러스터 기본값) | 해당 클레임에 사용할 StorageClass입니다. init이 --storage-class 값 또는 감지된 기본값으로 채웁니다. |
executor.persistence.size | 5Gi | 클레임 크기입니다. |
executor.persistence.accessModes | [ReadWriteOnce] | 클레임 액세스 모드입니다. |
executor.cluster는 단일 매핑으로, 실행기당 클러스터는 하나입니다. clusters 목록을 사용하면 렌더링에 실패합니다.
영속성
| 키 | 기본값 | 의미 |
|---|---|---|
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 | "" | gateway가 요구하는 선택적 hosted-domain 클레임입니다. 허용 목록 조회 전에 워크스페이스 외부 token을 거부합니다. |
clctl.gateway.allowedOperators | [] (닫힘) | ConfigMap으로 렌더링되는 연산자 이메일 허용 목록입니다. 교체하려면 values를 변경한 후 helm upgrade를 실행합니다. |
clctl.gateway.requireVerifiedEmail | true | 연산자 token에 email_verified 클레임을 요구합니다. jwksUri와 issuer를 모두 설정하지 않은 채 false로 두면 렌더링에 실패합니다. |
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 인그레스 소스입니다. 비어 있으면 차트의 네임스페이스에 있는 모든 파드를 허용합니다. 인그레스를 사용할 때는 인그레스 controller의 네임스페이스 레이블로 설정하십시오. |
clctl.gateway.rateLimit.requestsPerMinute | 30 | 연산자별 요청 속도 제한입니다. |
clctl.gateway.ingress.enabled | false | gateway용 인그레스를 렌더링합니다. 비활성화하면 연산자는 kubectl port-forward로 gateway에 연결합니다. 인그레스 controller나 cert-manager는 필요하지 않습니다. |
clctl.gateway.ingress.className, hosts, tls, annotations | "", [], [], {} | 표준 인그레스 필드입니다. tls는 kubernetes.io/tls 시크릿을 참조합니다. |
networkPolicy
| 키 | 기본값 | 의미 |
|---|---|---|
networkPolicy.enabled | true | 이그레스 허용 목록을 포함하는 기본 거부 NetworkPolicy를 생성합니다. 적용하려면 이를 지원하는 CNI가 필요합니다. |
networkPolicy.allowEgressCIDRs | [] (init --egress-cidrs가 채움) | 커넥터 엔드포인트가 위치한 CIDR입니다. 관리형 모드에서 플랫폼 차트가 Amazon ECR에 있는 경우, 해당 리전의 ECR 및 STS 범위 또는 미러의 범위도 포함합니다. 이를 지원하는 CNI에서는 이 값을 설정하기 전까지 커넥터의 이그레스가 허용되지 않습니다. init는 이 값이 알려진 경우에만 정책을 활성화된 상태로 준비합니다. |
networkPolicy.allowEgressPorts | [443] | allowEgressCIDRs에 대해 열어 둘 포트입니다. 엔드포인트가 기본 포트가 아닌 포트에서 수신 대기하는 경우 재정의하십시오. |
networkPolicy.clickhouseNamespaces | [] | kubernetes.io/metadata.name 레이블과 일치하는 ClickHouse 서비스의 네임스페이스입니다. 실행기가 생성하는 네임스페이스는 실행기가 부여하는 clicklink.clickhouse.com/managed-by=executor 레이블에 의해 무조건 허용되므로, 관리형 설치에서는 실행기 외부에서 생성된 네임스페이스만 나열합니다. 비어 있으면 troubleshooter 정책은 최상위 instances 맵의 namespace 값으로 폴백합니다. 스크레이퍼 정책에는 폴백이 없으므로 스크레이핑 대상 네임스페이스를 여기에 나열하십시오. |
networkPolicy.metricsScrapeSelector | {} | 레이블을 사용해 메트릭 스크레이프 인그레스를 특정 Prometheus 네임스페이스로 제한합니다. 비어 있으면 차트의 네임스페이스에 있는 모든 파드에서 스크레이프를 허용합니다. |
networkPolicy.kubeletProbeCIDRs | [] | 큐블릿 상태 probe 요청의 출발지 CIDR(노드 IP)입니다. 비어 있으면 대부분의 CNI에서 적용되는 큐블릿 예외와 동일하게 모든 출발지의 probe 인그레스를 허용합니다. 엄격한 기본 거부 환경에서는 명시적으로 설정하십시오. |
networkPolicy.apiserverCIDRs | [] (init --managed가 클러스터 VPC에서 채움) | Kubernetes API server CIDR입니다. 비어 있으면 API server 이그레스 규칙이 생성되지 않으며, 관리형 Kubernetes에서는 이를 설정할 때까지 데몬이 첫 번째 token 요청에 실패합니다. API server 자체 주소는 클러스터의 수명 동안 변경되므로, 해당 주소가 아닌 VPC의 범위를 고정하십시오. |