> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse 클러스터 디스커버리 문서

# 클러스터 디스커버리

<div id="overview">
  ## 개요
</div>

ClickHouse의 클러스터 디스커버리 기능을 사용하면 설정 파일에 각 노드를 명시적으로 정의하지 않아도 노드가 자동으로 서로를 발견하고 스스로 등록할 수 있어 클러스터 구성이 간소화됩니다. 특히 각 노드를 수동으로 정의해야 해 번거로운 경우에 유용합니다.

<Note>
  클러스터 디스커버리는 실험적 기능이므로 향후 버전에서 변경되거나 제거될 수 있습니다.
  활성화하려면 설정 파일에 `allow_experimental_cluster_discovery` 설정을 추가하십시오:

  ```xml theme={null}
  <clickhouse>
      <!-- ... -->
      <allow_experimental_cluster_discovery>1</allow_experimental_cluster_discovery>
      <!-- ... -->
  </clickhouse>
  ```
</Note>

<div id="remote-servers-configuration">
  ## 원격 서버 구성
</div>

<div id="traditional-manual-configuration">
  ### 기존의 수동 구성
</div>

기존에는 ClickHouse에서 클러스터의 각 세그먼트와 레플리카를 구성 파일에 수동으로 지정해야 했습니다:

```xml theme={null}
<remote_servers>
    <cluster_name>
        <shard>
            <replica>
                <host>node1</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node2</host>
                <port>9000</port>
            </replica>
        </shard>
        <shard>
            <replica>
                <host>node3</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node4</host>
                <port>9000</port>
            </replica>
        </shard>
    </cluster_name>
</remote_servers>

```

<div id="using-cluster-discovery">
  ### 클러스터 디스커버리 사용
</div>

클러스터 디스커버리를 사용하면 각 노드를 명시적으로 정의하는 대신 ZooKeeper에 경로만 지정하면 됩니다. ZooKeeper에서 이 경로 아래에 등록된 모든 노드는 자동으로 감지되어 클러스터에 추가됩니다.

```xml theme={null}
<remote_servers>
    <cluster_name>
        <discovery>
            <path>/clickhouse/discovery/cluster_name</path>

            <!-- # 선택적 구성 매개변수: -->

            <!-- ## 클러스터 내 다른 모든 노드에 접근하기 위한 인증 자격 증명: -->
            <!-- <user>user1</user> -->
            <!-- <password>pass123</password> -->
            <!-- ### 비밀번호 대신 서버 간 시크릿을 사용할 수도 있습니다: -->
            <!-- <secret>secret123</secret> -->

            <!-- ## 현재 노드의 세그먼트(아래 참조): -->
            <!-- <shard>1</shard> -->

            <!-- ## 옵저버 모드(아래 참조): -->
            <!-- <observer/> -->
        </discovery>
    </cluster_name>
</remote_servers>
```

특정 노드의 세그먼트 번호를 지정하려면 `<discovery>` 섹션 안에 `<shard>` 태그를 포함할 수 있습니다:

`node1` 및 `node2`의 경우:

```xml theme={null}
<discovery>
    <path>/clickhouse/discovery/cluster_name</path>
    <shard>1</shard>
</discovery>
```

`node3` 및 `node4`는 다음과 같습니다:

```xml theme={null}
<discovery>
    <path>/clickhouse/discovery/cluster_name</path>
    <shard>2</shard>
</discovery>
```

<div id="observer-mode">
  ### 옵저버 모드
</div>

옵저버 모드로 구성된 노드는 스스로를 레플리카로 등록하지 않습니다.
이 노드들은 능동적으로 참여하지 않고 클러스터 내의 다른 활성 레플리카를 관찰하고 발견만 합니다.
옵저버 모드를 활성화하려면 `<discovery>` 섹션 안에 `<observer/>` 태그를 포함하십시오:

```xml theme={null}
<discovery>
    <path>/clickhouse/discovery/cluster_name</path>
    <observer/>
</discovery>
```

<div id="discovery-of-clusters">
  ### 클러스터 디스커버리
</div>

때로는 클러스터 내 호스트뿐 아니라 클러스터 자체를 추가하거나 제거해야 할 수도 있습니다. 이때 여러 클러스터의 루트 경로를 가리키는 `<multicluster_root_path>` 노드를 사용할 수 있습니다:

```xml theme={null}
<remote_servers>
    <some_unused_name>
        <discovery>
            <multicluster_root_path>/clickhouse/discovery</multicluster_root_path>
            <observer/>
        </discovery>
    </some_unused_name>
</remote_servers>
```

이 경우, 다른 호스트가 경로 `/clickhouse/discovery/some_new_cluster`에 자신을 등록하면 `some_new_cluster`라는 이름의 클러스터가 추가됩니다.

두 기능을 동시에 사용할 수 있습니다. 호스트는 클러스터 `my_cluster`에 자신을 등록하는 동시에 다른 클러스터도 디스커버리할 수 있습니다:

```xml theme={null}
<remote_servers>
    <my_cluster>
        <discovery>
            <path>/clickhouse/discovery/my_cluster</path>
        </discovery>
    </my_cluster>
    <some_unused_name>
        <discovery>
            <multicluster_root_path>/clickhouse/discovery</multicluster_root_path>
            <observer/>
        </discovery>
    </some_unused_name>
</remote_servers>
```

제한 사항:

* 동일한 `remote_servers` 하위 트리에서는 `<path>`와 `<multicluster_root_path>`를 함께 사용할 수 없습니다.
* `<multicluster_root_path>`는 `<observer/>`와 함께만 사용할 수 있습니다.
* Keeper의 경로 마지막 부분은 클러스터 이름으로 사용되며, 등록 시 이름은 XML 태그에서 가져옵니다.

<div id="use-cases-and-limitations">
  ## 사용 사례 및 제한 사항
</div>

지정된 ZooKeeper 경로에 노드가 추가되거나 제거되면, 구성 변경이나 서버 재시작 없이 클러스터에서 자동으로 감지되거나 제거됩니다.

하지만 이러한 변경 사항은 클러스터 구성에만 영향을 미치며, 데이터나 기존 데이터베이스 및 테이블에는 영향을 미치지 않습니다.

다음은 3개의 노드로 구성된 클러스터 예시입니다:

```xml theme={null}
<remote_servers>
    <default>
        <discovery>
            <path>/clickhouse/discovery/default_cluster</path>
        </discovery>
    </default>
</remote_servers>
```

```sql theme={null}
SELECT * EXCEPT (default_database, errors_count, slowdowns_count, estimated_recovery_time, database_shard_name, database_replica_name)
FROM system.clusters WHERE cluster = 'default';

┌─cluster─┬─shard_num─┬─shard_weight─┬─replica_num─┬─host_name────┬─host_address─┬─port─┬─is_local─┬─user─┬─is_active─┐
│ default │         1 │            1 │           1 │ 92d3c04025e8 │ 172.26.0.5   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           2 │ a6a68731c21b │ 172.26.0.4   │ 9000 │        1 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           3 │ 8e62b9cb17a1 │ 172.26.0.2   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
└─────────┴───────────┴──────────────┴─────────────┴──────────────┴──────────────┴──────┴──────────┴──────┴───────────┘
```

```sql theme={null}
CREATE TABLE event_table ON CLUSTER default (event_time DateTime, value String)
ENGINE = ReplicatedMergeTree('/clickhouse/tables/event_table', '{replica}')
ORDER BY event_time PARTITION BY toYYYYMM(event_time);

INSERT INTO event_table ...
```

그런 다음 설정 파일의 `remote_servers` 섹션에 동일한 항목을 사용해 새 노드를 시작하여 클러스터에 추가합니다:

```response theme={null}
┌─cluster─┬─shard_num─┬─shard_weight─┬─replica_num─┬─host_name────┬─host_address─┬─port─┬─is_local─┬─user─┬─is_active─┐
│ default │         1 │            1 │           1 │ 92d3c04025e8 │ 172.26.0.5   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           2 │ a6a68731c21b │ 172.26.0.4   │ 9000 │        1 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           3 │ 8e62b9cb17a1 │ 172.26.0.2   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
│ default │         1 │            1 │           4 │ b0df3669b81f │ 172.26.0.6   │ 9000 │        0 │      │      ᴺᵁᴸᴸ │
└─────────┴───────────┴──────────────┴─────────────┴──────────────┴──────────────┴──────┴──────────┴──────┴───────────┘
```

네 번째 노드는 클러스터에 참여하고 있지만, 테이블 `event_table`은 여전히 처음 3개의 노드에만 존재합니다:

```sql theme={null}
SELECT hostname(), database, table FROM clusterAllReplicas(default, system.tables) WHERE table = 'event_table' FORMAT PrettyCompactMonoBlock

┌─hostname()───┬─database─┬─table───────┐
│ a6a68731c21b │ default  │ event_table │
│ 92d3c04025e8 │ default  │ event_table │
│ 8e62b9cb17a1 │ default  │ event_table │
└──────────────┴──────────┴─────────────┘
```

모든 노드에 테이블을 복제해야 하는 경우, 클러스터 디스커버리 대신 [Replicated](/docs/ko/reference/engines/database-engines/replicated) 데이터베이스 엔진을 사용할 수 있습니다.