# Протокол службы обнаружения

> Обнаружение других участников etcd на этапе начальной инициализации кластера

---

Индекс LLMS: [llms.txt](/ru/llms.txt)

---

Протокол службы обнаружения помогает новому участнику etcd найти остальных участников на этапе начальной инициализации кластера с помощью общего URL обнаружения.

Протокол используется _только_ при начальной инициализации и не подходит для реконфигурации во время выполнения или мониторинга кластера.

Один новый токен обнаружения предназначен для инициализации одного _уникального_ кластера etcd. Один токен может представлять только один кластер. После запуска протокола для токена его нельзя использовать для инициализации другого кластера, даже если первый процесс завершился с ошибкой на полпути.

Далее процесс обнаружения рассматривается на примере самостоятельно размещённого кластера. Общедоступная служба discovery.etcd.io работает так же, но скрывает неудобные URL, автоматически создаёт UUID и защищает от чрезмерного количества запросов. В основе общедоступной службы всё равно лежит кластер etcd, используемый как описанное здесь хранилище данных.

## Рабочий процесс протокола {#protocol-workflow}

Протокол использует внутренний кластер etcd для координации начальной инициализации нового кластера. Сначала все новые участники взаимодействуют со службой и совместно формируют ожидаемый список. Затем каждый участник запускает сервер с этим списком, что выполняет ту же функцию, что и флаг -initial-cluster.

В примере ниже каждый шаг для наглядности показан в формате curl.

По соглашению протокол обнаружения etcd использует префикс ключей `_etcd/registry`. Если кластер службы расположен на `http://example.com`, полный URL пространства ключей будет `http://example.com/v2/keys/_etcd/registry`. Этот URL используется в примерах как префикс.

### Создание нового токена обнаружения {#creating-a-new-discovery-token}

Создайте уникальный токен, идентифицирующий новый кластер. На следующих шагах он будет уникальным префиксом пространства ключей обнаружения. Простой способ создать токен — использовать `uuidgen`:

```
UUID=$(uuidgen)
```

### Указание ожидаемого размера кластера {#specifying-the-expected-cluster-size}

Для токена необходимо указать размер кластера. Служба использует его, чтобы определить, когда найдены все участники, изначально формирующие кластер.

```
curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/_config/size -d value=${cluster_size}
```

Обычно размер кластера равен 3, 5 или 7. Подробнее см. в разделе [оптимального размера кластера][cluster-size].

### Запуск процессов etcd {#bringing-up-etcd-processes}

Передайте URL обнаружения флагу `-discovery` и запустите процессы etcd. При наличии флага `-discovery` каждый процесс автоматически выполняет следующие шаги.

### Саморегистрация {#registering-itself}

Сначала процесс etcd регистрирует себя как участника по URL обнаружения. Для этого ID участника создаётся как ключ URL.

```
curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/${member_id}?prevExist=false -d value="${member_name}=${member_peer_url_1}&${member_name}=${member_peer_url_2}"
```

### Проверка состояния {#checking-the-status}

Процесс проверяет ожидаемый размер кластера и состояние регистрации по URL, а затем выбирает следующее действие.

```
curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}/_config/size
curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}
```

Если зарегистрированных участников недостаточно, процесс ожидает появления остальных.

Если участников больше ожидаемого размера N, первые N принимаются за список кластера. Если текущий участник входит в список, процедура завершается успешно и получает из списка всех одноранговых участников. В противном случае она завершается ошибкой, сообщающей, что кластер заполнен.

В реализации etcd участник может проверить состояние кластера ещё до саморегистрации, поэтому при заполненном кластере отказ произойдёт быстро.

### Ожидание всех участников {#waiting-for-all-members}

Процесс ожидания подробно описан в [документации API etcd][api].

```
curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}?wait=true&waitIndex=${current_etcd_index}
```

Он продолжает ожидать, пока не найдёт всех участников.

## Общедоступная служба обнаружения {#public-discovery-service}

CoreOS Inc. размещает общедоступную службу на https://discovery.etcd.io/ с дополнительными удобствами.

### Скрытие префикса ключа {#mask-key-prefix}

Служба перенаправляет `https://discovery.etcd.io/${UUID}` к стоящему за ней кластеру etcd для ключа `/v2/keys/_etcd/registry`. Это скрывает префикс реестра и делает URL короче и понятнее.

### Получение нового токена {#get-new-token}

```
GET /new

Sent query:
	size=${cluster_size}
Possible status codes:
	200 OK
	400 Bad Request
200 Body:
	generated discovery url
```

Процесс создания следует шагам от [создания нового токена][new-discovery-token] до [указания ожидаемого размера кластера][expected-cluster-size].

### Проверка состояния обнаружения {#check-discovery-status}

```
GET /${UUID}
```

Состояние токена, включая зарегистрированные машины, можно проверить, запросив значение UUID.

### Репозиторий с открытым исходным кодом {#open-source-repository}

Репозиторий расположен по адресу https://github.com/coreos/discovery.etcd.io. На его основе можно создать собственную службу обнаружения.

[api]: https://etcd.io/docs/v2.3/api#waiting-for-a-change
[cluster-size]: https://etcd.io/docs/v2.3/admin_guide#optimal-cluster-size
[expected-cluster-size]: #specifying-the-expected-cluster-size
[new-discovery-token]: #creating-a-new-discovery-token