구성 파일(Configuration Files)
구성 파일(Configuration Files)
ClickHouse 서버는 XML 또는 YAML 구문의 구성 파일로 설정할 수 있습니다. 이 문서에서는 구성 파일 병합 규칙, 환경 변수·ZooKeeper 치환, incl을 통한 파일 내용 치환, 암호화, 그리고 YAML 작성 요령을 설명할게요.
출처: 문서
본문
XML 기반 설정 프로필과 구성 파일은 ClickHouse Cloud에서 지원되지 않습니다. 따라서 ClickHouse Cloud에서는 config.xml 파일을 찾을 수 없습니다. 대신 SQL 명령을 사용해 설정 프로필을 통해 설정을 관리해야 합니다. 자세한 내용은 “설정 구성하기”를 참고하세요.
ClickHouse 서버는 XML 또는 YAML 구문의 구성 파일로 설정할 수 있습니다. 대부분의 설치 유형에서 ClickHouse 서버는 /etc/clickhouse-server/config.xml을 기본 구성 파일로 사용해 실행되지만, 서버 시작 시 명령줄 옵션 --config-file 또는 -C로 구성 파일의 위치를 수동으로 지정하는 것도 가능합니다. 추가 구성 파일은 기본 구성 파일에 상대적인 config.d/ 디렉터리에 놓을 수 있습니다. 예를 들어 /etc/clickhouse-server/config.d/ 디렉터리에요. 이 디렉터리의 파일과 기본 구성은 ClickHouse 서버에 구성이 적용되기 전에 전처리 단계에서 병합됩니다. 구성 조각은 전체 경로의 사전식 순서로 병합됩니다. 표준 config.d/ 디렉터리의 파일의 경우 이것은 파일 이름 순서와 동일합니다. 레거시 conf.d/ 디렉터리도 병합됩니다. conf.d는 config.d보다 먼저 정렬되므로 두 디렉터리가 모두 존재하면 모든 조각이 먼저 처리됩니다. 업데이트를 단순화하고 모듈화를 개선하기 위해 기본 config.xml 파일은 수정하지 않고 추가 커스터마이징을 config.d/에 두는 것이 모범 사례입니다. ClickHouse Keeper 구성은 /etc/clickhouse-keeper/keeper_config.xml에 있습니다. 마찬가지로 Keeper의 추가 구성 파일은 /etc/clickhouse-keeper/keeper_config.d/에 놓아야 합니다. XML과 YAML 구성 파일을 섞을 수 있습니다. 예를 들어 기본 구성 파일 config.xml과 추가 구성 파일 config.d/network.xml, config.d/timezone.yaml, config.d/keeper.yaml을 가질 수 있습니다. 단일 구성 파일 내에서 XML과 YAML을 혼합하는 것은 지원되지 않습니다. XML 구성 파일은 최상위 태그로 <clickhouse>...</clickhouse>를 사용해야 합니다. YAML 구성 파일에서는 clickhouse:가 선택 사항이며, 없으면 파서가 자동으로 삽입합니다.
구성 병합
두 구성 파일(보통 기본 구성 파일과 config.d/의 다른 구성 파일)은 다음과 같이 병합됩니다:
- 노드(즉 요소로 이어지는 경로)가 두 파일 모두에 나타나고
replace또는remove속성이 없으면, 병합된 구성 파일에 포함되며 두 노드의 자식이 모두 포함되고 재귀적으로 병합됩니다. - 두 노드 중 하나에
replace속성이 있으면 병합된 구성 파일에 포함되지만,replace속성이 있는 노드의 자식만 포함됩니다. - 두 노드 중 하나에
remove속성이 있으면 그 노드는 병합된 구성 파일에 포함되지 않습니다(이미 존재한다면 삭제됩니다).
예를 들어 두 개의 구성 파일이 주어졌다고 가정해 보겠습니다:
config.xml
<clickhouse>
<config_a>
<setting_1>1</setting_1>
</config_a>
<config_b>
<setting_2>2</setting_2>
</config_b>
<config_c>
<setting_3>3</setting_3>
</config_c>
</clickhouse>
config.d/other_config.xml
<clickhouse>
<config_a>
<setting_4>4</setting_4>
</config_a>
<config_b replace="replace">
<setting_5>5</setting_5>
</config_b>
<config_c remove="remove">
<setting_6>6</setting_6>
</config_c>
</clickhouse>
결과적으로 병합된 구성 파일은 다음과 같습니다:
<clickhouse>
<config_a>
<setting_1>1</setting_1>
<setting_4>4</setting_4>
</config_a>
<config_b>
<setting_5>5</setting_5>
</config_b>
</clickhouse>
환경 변수와 ZooKeeper 노드로 치환하기
요소의 값이 환경 변수의 값으로 대체되어야 한다는 것을 지정하려면 from_env 속성을 사용할 수 있습니다. 예를 들어 환경 변수 $MAX_QUERY_SIZE = 150000일 때:
<clickhouse>
<profiles>
<default>
<max_query_size from_env="MAX_QUERY_SIZE"/>
</default>
</profiles>
</clickhouse>
결과 구성은 다음과 같습니다:
<clickhouse>
<profiles>
<default>
<max_query_size>150000</max_query_size>
</default>
</profiles>
</clickhouse>
from_zk(ZooKeeper 노드)를 사용해도 같은 것이 가능합니다:
<clickhouse>
<postgresql_port from_zk="/zk_configs/postgresql_port"/>
</clickhouse>
# clickhouse-keeper-client
/ :) touch /zk_configs
/ :) create /zk_configs/postgresql_port "9005"
/ :) get /zk_configs/postgresql_port
9005
다음 구성이 결과로 나옵니다:
<clickhouse>
<postgresql_port>9005</postgresql_port>
</clickhouse>
기본값
from_env 또는 from_zk 속성이 있는 요소는 추가로 replace="1" 속성을 가질 수 있습니다(후자는 from_env/from_zk 앞에 와야 합니다). 이 경우 요소는 기본값을 정의할 수 있습니다. 환경 변수나 ZooKeeper 노드가 설정되어 있으면 그 값을 취하고, 그렇지 않으면 기본값을 취합니다. 앞의 예제를 반복하되 MAX_QUERY_SIZE가 설정되지 않았다고 가정합니다:
<clickhouse>
<profiles>
<default>
<max_query_size replace="1" from_env="MAX_QUERY_SIZE">150000</max_query_size>
</default>
</profiles>
</clickhouse>
결과 구성:
<clickhouse>
<profiles>
<default>
<max_query_size>150000</max_query_size>
</default>
</profiles>
</clickhouse>
파일 내용으로 치환하기
구성의 일부를 파일 내용으로 대체하는 것도 가능합니다. 두 가지 방법으로 할 수 있습니다:
- 값 치환: 요소에
incl속성이 있으면 그 값은 참조된 파일의 내용으로 대체됩니다. 치환이 있는 파일의 경로는 서버 구성의include_from요소로 설정됩니다. 기본 경로는 없으므로 지정할 때만 치환이 읽힙니다. 치환 값은 이 파일의/clickhouse/substitution_name요소에 지정됩니다.incl에 지정된 치환이 존재하지 않으면 로그에 기록됩니다. ClickHouse가 누락된 치환을 로깅하지 못하게 하려면optional="true"속성을 지정하세요(예: macros 설정). - 요소 치환: 전체 요소를 치환으로 대체하려면 요소 이름으로
include를 사용하세요. 요소 이름include는from_zk = "/path/to/node"속성과 결합할 수 있습니다. 이 경우 요소 값은/path/to/node의 ZooKeeper 노드 내용으로 대체됩니다. 전체 XML 하위 트리를 ZooKeeper 노드로 저장해도 동작하며, 소스 요소에 완전히 삽입됩니다.
26.8 버전에서 변경됨: 그 버전 이전에는 include_from이 지정되지 않았어도 파일 /etc/metrika.xml이 존재할 때마다 암시적으로 사용되었습니다. 그 파일에 의존한다면 include_from에 경로를 명시적으로 지정하세요. include_from은 각 구성 파일에서 개별적으로 읽힌다는 점에 유의하세요: 기본 서버 구성과 별도로 로드되는 파일 — 사용자 구성(예: 기본 파일에 포함되지 않은 users.xml)과 XML 딕셔너리 구성 — 은 각각 자체 include_from 요소가 필요합니다. 기본 서버 구성에만 지정하는 것은 그들에 적용되지 않습니다.
병합하는 대신 치환 내용을 기존 구성과 병합하려면 merge="true" 속성을 사용할 수 있습니다. 예: <include from_zk="/some_path" merge="true">. 이 경우 기존 구성은 치환 내용과 병합되고 기존 구성 설정은 치환 값으로 대체됩니다.
구성 암호화 및 숨기기
대칭 암호화를 사용해 구성 요소(예: 일반 텍스트 비밀번호나 개인 키)를 암호화할 수 있습니다. 이렇게 하려면 먼저 암호화 코덱을 구성한 다음, 암호화할 요소에 암호화 코덱의 이름을 값으로 하는 encrypted_by 속성을 추가합니다. from_zk, from_env, incl 속성이나 include 요소와 달리 전처리 파일에서는 치환(즉 암호화된 값의 복호화)이 수행되지 않습니다. 복호화는 서버 프로세스에서 런타임에만 일어납니다. 예를 들어:
<clickhouse>
<encryption_codecs>
<aes_128_gcm>
<key_hex>00112233445566778899aabbccddeeff</key_hex>
<nonce_hex>000102030405060708090a0b0c0d0e0f</nonce_hex>
</aes_128_gcm>
</encryption_codecs>
<profiles>
<default>
<password encrypted_by="aes_128_gcm">encrypted_value_here</password>
</default>
</profiles>
</clickhouse>
from_env와 from_zk 속성은 encryption_codecs에도 적용할 수 있습니다. 암호화 키와 암호화된 값은 어느 구성 파일에서든 정의할 수 있습니다. encrypt_decrypt 프로그램을 사용해 값을 암호화할 수 있습니다.
암호화된 구성 요소가 있어도 암호화된 요소는 여전히 전처리된 구성 파일에 나타납니다. ClickHouse 배포에서 이것이 문제라면 두 가지 대안이 있습니다: 전처리 파일의 파일 권한을 600으로 설정하거나 hide_in_preprocessed 속성을 사용하세요.
사용자 설정
config.xml 파일은 사용자 설정, 프로필, 쿼터가 있는 별도 구성을 지정할 수 있습니다. 이 구성에 대한 상대 경로는 users_config 요소에 설정됩니다. 기본값은 users.xml입니다. users_config가 생략되면 사용자 설정, 프로필, 쿼터가 config.xml에 직접 지정됩니다. 사용자 구성은 config.xml과 config.d/처럼 별도 파일로 분할할 수 있습니다. 디렉터리 이름은 users_config 설정에서 .xml 접미사를 제거하고 .d를 연결한 것으로 정의됩니다. users_config가 기본적으로 users.xml이므로 users.d 디렉터리가 기본적으로 사용됩니다. 사용자 구성 조각은 전체 경로의 사전식 순서로 병합됩니다. 표준 users.d/ 디렉터리의 파일의 경우 이것은 파일 이름 순서와 동일합니다. 레거시 conf.d/ 디렉터리도 병합됩니다. conf.d는 users.d보다 먼저 정렬되므로 두 디렉터리가 모두 존재하면 모든 조각이 먼저 처리됩니다. 구성 파일은 먼저 설정을 고려하여 병합되고, include는 그 후에 처리된다는 점에 유의하세요.
XML 예제
예를 들어 각 사용자에 대해 별도의 구성 파일을 가질 수 있습니다:
<clickhouse>
<profiles>
<default>
<max_query_size>1000000</max_query_size>
</default>
</profiles>
</clickhouse>
YAML 예제
기본 구성을 YAML로 쓴 것은 여기: config.yaml.example에서 볼 수 있습니다. ClickHouse 구성 측면에서 YAML과 XML 형식 사이에는 몇 가지 차이점이 있습니다. YAML 형식으로 구성을 작성하는 요령은 아래에 제시됩니다.
텍스트 값을 가진 XML 태그는 YAML 키-값 쌍으로 표현됩니다:
clickhouse:
config_a:
setting_1: 1
setting_4: 4
config_b:
setting_5: 5
중첩된 XML 노드는 YAML 맵으로 표현됩니다:
clickhouse:
config_a:
setting_1: 1
nested:
child_setting: value
같은 XML 태그를 여러 번 만들려면 YAML 시퀀스를 사용하세요:
clickhouse:
config:
- setting: value1
- setting: value2
XML 속성을 제공하려면 @ 접두사가 있는 속성 키를 사용할 수 있습니다. 참고로 @는 YAML 표준에서 예약되어 있으므로 큰따옴표로 감싸야 합니다:
clickhouse:
config_a:
setting_with_attr:
"@replace": "replace"
"#text": "value"
위에서 언급한 구문은 XML 속성을 가진 XML 텍스트 노드를 YAML로 표현하지 못합니다. 이 특별한 경우는 #text 속성 키를 사용해 달성할 수 있습니다:
clickhouse:
profiles:
default:
max_query_size:
"@from_env": "MAX_QUERY_SIZE"
"#text": "150000"
구현 세부 사항
각 구성 파일에 대해 서버는 시작 시 file-preprocessed.xml 파일도 생성합니다. 이 파일들은 완료된 모든 치환과 오버라이드를 포함하며 정보 제공용입니다. 구성 파일에서 ZooKeeper 치환이 사용되었지만 서버 시작 시 ZooKeeper를 사용할 수 없으면 서버는 전처리 파일에서 구성을 로드합니다. 서버는 구성 파일과 치환·오버라이드 수행에 사용된 파일 및 ZooKeeper 노드의 변경을 추적하고, 사용자와 클러스터에 대한 설정을 즉시 다시 로드합니다. 즉 서버를 재시작하지 않고도 클러스터, 사용자 및 그 설정을 수정할 수 있습니다.