Руководство для разработчиков

• 1: Протокол службы обнаружения
• 2: Настройка локального кластера
• 3: Интеракция с etcd
• 4: Зачем нужен шлюз gRPC
• 5: Именование и обнаружение gRPC
• 6: Встраивание etcd в Go-приложение
• 7: Ограничения системы
• 8: Возможности etcd
• 9: Справочник API
• 10: Справочник API: конкурентность

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

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

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

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

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

Рабочий процесс протокола

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

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

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

Создание нового токена обнаружения

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

UUID=$(uuidgen)

Указание ожидаемого размера кластера

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

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

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

Запуск процессов etcd

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

Саморегистрация

Сначала процесс 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}"

Проверка состояния

Процесс проверяет ожидаемый размер кластера и состояние регистрации по 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 участник может проверить состояние кластера ещё до саморегистрации, поэтому при заполненном кластере отказ произойдёт быстро.

Ожидание всех участников

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

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

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

Общедоступная служба обнаружения

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

Скрытие префикса ключа

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

Получение нового токена

GET /new

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

Процесс создания следует шагам от создания нового токена до указания ожидаемого размера кластера .

Проверка состояния обнаружения

GET /${UUID}

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

Репозиторий с открытым исходным кодом

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

2 - Настройка локального кластера

Для тестирования и разработки быстрее и проще всего настроить локальный кластер. Промышленное развёртывание описано в разделе кластеризации .

Локальный автономный кластер

Запуск кластера

Чтобы развернуть автономный кластер etcd, выполните:

$ ./etcd
...

Если бинарный файл etcd отсутствует в текущем рабочем каталоге, он может находиться в $GOPATH/bin/etcd или /usr/local/bin/etcd. Укажите правильный путь при запуске.

Работающий участник etcd принимает клиентские запросы на localhost:2379.

Взаимодействие с кластером

Используйте etcdctl для взаимодействия с работающим кластером:

1. Сохраните в кластере пример пары «ключ — значение»:

     $ ./etcdctl put foo bar
     OK

   Вывод OK означает, что пара успешно сохранена.

2. Получите значение ключа foo:

   $ ./etcdctl get foo
   bar

   Если возвращено bar, взаимодействие с кластером etcd работает ожидаемым образом.

Локальный кластер из нескольких участников

Запуск кластера

В корне git-репозитория etcd находится Procfile, упрощающий настройку локального кластера из нескольких участников. Перейдите в корень дерева исходного кода etcd и выполните следующие действия:

1. Установите goreman для управления приложениями на основе Procfile:

   $ go install github.com/mattn/goreman@latest

2. Запустите кластер через goreman, используя штатный Procfile etcd:

   $ goreman -f Procfile start

   Участники запускаются и принимают клиентские запросы соответственно на localhost:2379, localhost:22379 и localhost:32379.

Взаимодействие с кластером

Используйте etcdctl для взаимодействия с работающим кластером:

1. Выведите список участников:

   $ etcdctl --write-out=table --endpoints=localhost:2379 member list

   Список участников etcd выглядит следующим образом:

   +------------------+---------+--------+------------------------+------------------------+
   |        ID        | STATUS  |  NAME  |       PEER ADDRS       |      CLIENT ADDRS      |
   +------------------+---------+--------+------------------------+------------------------+
   | 8211f1d0f64f3269 | started | infra1 | http://127.0.0.1:2380  | http://127.0.0.1:2379  |
   | 91bc3c398fb3c146 | started | infra2 | http://127.0.0.1:22380 | http://127.0.0.1:22379 |
   | fd422379fda50e48 | started | infra3 | http://127.0.0.1:32380 | http://127.0.0.1:32379 |
   +------------------+---------+--------+------------------------+------------------------+

2. Сохраните в кластере пример пары «ключ — значение»:

   $ etcdctl put foo bar
   OK

   Вывод OK означает, что пара успешно сохранена.

Проверка отказоустойчивости

Чтобы проверить отказоустойчивость etcd, остановите одного участника и попытайтесь получить ключ.

1. Определите имя процесса участника, которого нужно остановить.

   Свойства кластера из нескольких участников перечислены в Procfile. Для примера возьмём участника с именем процесса etcd2.

2. Остановите участника:

   # kill etcd2
   $ goreman run stop etcd2

3. Сохраните ключ:

   $ etcdctl put key hello
   OK

4. Получите ключ, сохранённый на предыдущем шаге:

   $ etcdctl get key
   hello

5. Получите ключ у остановленного участника:

   $ etcdctl --endpoints=localhost:22379 get key

   Команда должна вывести ошибку из-за отсутствия соединения:

   2017/06/18 23:07:35 grpc: Conn.resetTransport failed to create client transport: connection error: desc = "transport: dial tcp 127.0.0.1:22379: getsockopt: connection refused"; Reconnecting to "localhost:22379"
   Error:  grpc: timed out trying to connect

6. Перезапустите остановленного участника:

   $ goreman run restart etcd2

7. Получите ключ у перезапущенного участника:

   $ etcdctl --endpoints=localhost:22379 get key
   hello

   После перезапуска участника соединение восстанавливается, и etcdctl снова может успешно получить ключ. Дополнительные сведения приведены в разделе взаимодействия с etcd .

3 - Интеракция с etcd

Пользователи чаще всего взаимодействуют с etcd, устанавливая или получая значение ключа. В этом разделе описано, как это сделать с помощью etcdctl — командной строки для взаимодействия с сервером etcd. Концепции, описанные здесь, должны применимы к gRPC–API или API клиентской библиотеки.

Версию API 2 или 3, которую etcdctl использует для связи с etcd, задаёт переменная окружения ETCDCTL_API. По умолчанию etcdctl из master (3.4) использует API v3, а версии 3.3 и старше — API v2.

Примечание: любой ключ, созданный с использованием v2 API, не сможет быть запрослен через v3 API. Запрос v3 API etcdctl get ключа v2 завершится с кодом 0 и без данных ключа, это ожидаемое поведение.

export ETCDCTL_API=3

Найти версии

etcdctl версия и версия сервера API могут быть полезны при определении подходящих команд для выполнения различных операций с etcd.

Здесь команда для поиска версий:

$ etcdctl version
etcdctl version: 3.1.0-alpha.0+git
API version: 3.1

Запишите ключ

Приложения хранят ключи в кластере etcd, записывая их в ключи. Каждый сохраненный ключ реплицируется всем участникам кластера etcd через протокол Raft для достижения согласованности и надежности.

Команда задаёт ключу foo значение bar:

$ etcdctl put foo bar
OK

Также ключ можно установить на определенный период времени, привязав к нему аренду.

Здесь команда для установки значения ключа foo1 равным bar1 для 10s.

$ etcdctl put foo1 bar1 --lease=1234abcd
OK

Прочитать ключи

Приложения могут читать из кластера etcd один ключ или диапазон ключей.

Предположим, что кластер etcd содержит следующие ключи:

foo = bar
foo1 = bar1
foo2 = bar2
foo3 = bar3

Команда читает значение ключа foo:

$ etcdctl get foo
foo
bar

Команда читает значение ключа foo в шестнадцатеричном формате:

$ etcdctl get foo --hex
\x66\x6f\x6f          # Key
\x62\x61\x72          # Value

Команда выводит только значение ключа foo:

$ etcdctl get foo --print-value-only
bar

Команда читает диапазон ключей от foo до foo3:

$ etcdctl get foo foo3
foo
bar
foo1
bar1
foo2
bar2

Команда читает все ключи с префиксом foo:

$ etcdctl get --prefix foo
foo
bar
foo1
bar1
foo2
bar2
foo3
bar3

Здесь команда для обхода всех ключей, предшествующих foo, с ограничением количества результатов до 2:

$ etcdctl get --prefix --limit=2 foo
foo
bar
foo1
bar1

Здесь команда для обхода всех ключей, предшествующих foo, с использованием RangeStream RPC. Результат идентичен однократному Range:

$ etcdctl get --stream --prefix foo
foo
bar
foo1
bar1
foo2
bar2
foo3
bar3

--stream не поддерживает --order, --sort-by и фильтры ревизий.

Прочитать версию ключа в прошлом состоянии

Приложения могут захотеть прочитать устаревшие версии ключа. Например, приложение может захотеть откатиться к старой конфигурации, обратившись к более ранней версии ключа. Альтернативно, приложение может получить согласованное представление над несколькими ключами через несколько запросов, обратившись к истории ключа. Поскольку каждое изменение в кластере etcd ключ-значение увеличивает глобальную ревизию кластера etcd, приложение может прочитать устаревшие ключи, предоставив более старую ревизию etcd.

Предположим, что кластер etcd уже содержит следующие ключи:

foo = bar         # revision = 2
foo1 = bar1       # revision = 3
foo = bar_new     # revision = 4
foo1 = bar1_new   # revision = 5

Здесь пример, как получить доступ к прошлым версиям ключей:

$ etcdctl get --prefix foo # access the most recent versions of keys
foo
bar_new
foo1
bar1_new

$ etcdctl get --prefix --rev=4 foo # access the versions of keys at revision 4
foo
bar_new
foo1
bar1

$ etcdctl get --prefix --rev=3 foo # access the versions of keys at revision 3
foo
bar
foo1
bar1

$ etcdctl get --prefix --rev=2 foo # access the versions of keys at revision 2
foo
bar

$ etcdctl get --prefix --rev=1 foo # access the versions of keys at revision 1

Читать ключи, которые не меньше указанного ключа по байтовому значению

Приложения могут хотеть прочитать ключи, которые больше или равны байтовому значению указанного ключа.

Предположим, что кластер etcd уже содержит следующие ключи:

a = 123
b = 456
z = 789

Команда читает ключи, байтовое значение которых не меньше ключа b:

$ etcdctl get --from-key b
b
456
z
789

Удалить ключи

Приложения могут удалить ключ или диапазон ключей из кластера etcd.

Предположим, что кластер etcd уже содержит следующие ключи:

foo = bar
foo1 = bar1
foo3 = bar3
zoo = val
zoo1 = val1
zoo2 = val2
a = 123
b = 456
z = 789

Здесь команда для удаления ключа foo:

$ etcdctl del foo
1 # one key is deleted

Здесь команда для удаления ключей от foo до foo9:

$ etcdctl del foo foo9
2 # two keys are deleted

Команда удаляет zoo и возвращает удалённую пару «ключ — значение»:

$ etcdctl del --prev-kv zoo
1   # one key is deleted
zoo # deleted key
val # the value of the deleted key

Команда удаляет ключи с префиксом zoo:

$ etcdctl del --prefix zoo
2 # two keys are deleted

Команда удаляет ключи, байтовое значение которых не меньше ключа b:

$ etcdctl del --from-key b
2 # two keys are deleted

Наблюдение за изменениями ключа

Приложения могут наблюдать за ключом или диапазоном ключей для мониторинга любых обновлений.

Здесь команда для наблюдения за ключом foo:

$ etcdctl watch foo
# in another terminal: etcdctl put foo bar
PUT
foo
bar

Команда наблюдает за ключом foo в шестнадцатеричном формате:

$ etcdctl watch foo --hex
# in another terminal: etcdctl put foo bar
PUT
\x66\x6f\x6f          # Key
\x62\x61\x72          # Value

Здесь команда для наблюдения за диапазоном ключей от foo до foo9:

$ etcdctl watch foo foo9
# in another terminal: etcdctl put foo bar
PUT
foo
bar
# in another terminal: etcdctl put foo1 bar1
PUT
foo1
bar1

Здесь команда для наблюдения за ключами с префиксом foo:

$ etcdctl watch --prefix foo
# in another terminal: etcdctl put foo bar
PUT
foo
bar
# in another terminal: etcdctl put fooz1 barz1
PUT
fooz1
barz1

Команда наблюдает за несколькими ключами foo и zoo:

$ etcdctl watch -i
$ watch foo
$ watch zoo
# in another terminal: etcdctl put foo bar
PUT
foo
bar
# in another terminal: etcdctl put zoo val
PUT
zoo
val

Наблюдение за историческими изменениями ключей

Программы могут хотеть наблюдать за историческими изменениями ключей в etcd. Например, программа может желать получать все модификации ключа; если программа останется подключена к etcd, то watch будет достаточно. Однако, если программа или etcd сбоит, изменение может произойти во время сбоя, и программа не получит обновление в реальном времени. Чтобы гарантировать доставку обновления, программа должна быть способна наблюдать за историческими изменениями ключей. Для этого программа может указать историческую ревизию при наблюдении, как при чтении прошлых версий ключей.

Предположим, что мы завершили следующую последовательность операций:

$ etcdctl put foo bar         # revision = 2
OK
$ etcdctl put foo1 bar1       # revision = 3
OK
$ etcdctl put foo bar_new     # revision = 4
OK
$ etcdctl put foo1 bar1_new   # revision = 5
OK

Здесь пример наблюдения за историческими изменениями:

# watch for changes on key `foo` since revision 2
$ etcdctl watch --rev=2 foo
PUT
foo
bar
PUT
foo
bar_new

# watch for changes on key `foo` since revision 3
$ etcdctl watch --rev=3 foo
PUT
foo
bar_new

Здесь пример наблюдения только с последней исторической измененной точки:

# watch for changes on key `foo` and return last revision value along with modified value
$ etcdctl watch --prev-kv foo
# in another terminal: etcdctl put foo bar_latest
PUT
foo         # key
bar_new     # last value of foo key before modification
foo         # key
bar_latest  # value of foo key after modification

Наблюдение за прогрессом

Приложение может проверять ход наблюдения, чтобы определить актуальность потока. Например, при обновлении кэша полезно знать, не устарел ли он относительно ревизии, полученной чтением по кворуму.

Запросы прогресса можно отправлять с помощью команды “progress” в интерактивном сеансе наблюдения, чтобы попросить сервер etcd отправлять уведомление о прогрессе в потоке наблюдения:

$ etcdctl watch -i
$ watch a
$ progress
progress notify: 1
# in another terminal: etcdctl put x 0
# in another terminal: etcdctl put y 1
$ progress
progress notify: 3

Компактированные ревизии

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

Здесь команда для компактного хранения ревизий:

$ etcdctl compact 5
compacted revision 5

# any revisions before the compacted one are not accessible
$ etcdctl get --rev=4 foo
Error:  rpc error: code = 11 desc = etcdserver: mvcc: required revision has been compacted

$ etcdctl get mykey -w=json
{"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":15,"raft_term":4}}

Выдать аренду

Приложения могут выдавать аренды для ключей из кластера etcd. Когда ключ прикреплен к аренде, его срок жизни связан с сроком жизни аренды, который в свою очередь регулируется временем жизни (TTL). Каждая аренда имеет минимальное значение времени жизни (TTL), указанное приложением при выдаче. Фактическое значение TTL арены составляет не менее минимального TTL и выбирается кластером etcd. После истечения срока жизни TTL арены она истекает и все прикрепленные ключи удаляются.

Команда выдаёт аренду:

# grant a lease with 60 second TTL
$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)

# attach key foo to lease 32695410dcc0ca06
$ etcdctl put --lease=32695410dcc0ca06 foo bar
OK

Отменить аренду

Приложения отменяют аренды по идентификатору арены. Отмена арены удаляет все связанные с ней ключи.

Предположим, что мы завершили следующую последовательность операций:

$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)
$ etcdctl put --lease=32695410dcc0ca06 foo bar
OK

Команда отзывает ту же аренду:

$ etcdctl lease revoke 32695410dcc0ca06
lease 32695410dcc0ca06 revoked

$ etcdctl get foo
# empty response since foo is deleted due to lease revocation

Сохраняйте аренду активной

Приложения могут поддерживать аренду активной обновлением её TTL, чтобы она не истекла.

Предположим, что мы завершили следующую последовательность операций:

$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)

Команда поддерживает ту же аренду активной:

$ etcdctl lease keep-alive 32695410dcc0ca06
lease 32695410dcc0ca06 keepalived with TTL(60)
lease 32695410dcc0ca06 keepalived with TTL(60)
lease 32695410dcc0ca06 keepalived with TTL(60)
...

Получить информацию об аренде

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

Предположим, что мы завершили следующую последовательность операций:

# grant a lease with 500 second TTL
$ etcdctl lease grant 500
lease 694d5765fc71500b granted with TTL(500s)

# attach key zoo1 to lease 694d5765fc71500b
$ etcdctl put zoo1 val1 --lease=694d5765fc71500b
OK

# attach key zoo2 to lease 694d5765fc71500b
$ etcdctl put zoo2 val2 --lease=694d5765fc71500b
OK

Команда получает сведения об аренде:

$ etcdctl lease timetolive 694d5765fc71500b
lease 694d5765fc71500b granted with TTL(500s), remaining(258s)

Команда получает сведения об аренде вместе с привязанными ключами:

$ etcdctl lease timetolive --keys 694d5765fc71500b
lease 694d5765fc71500b granted with TTL(500s), remaining(132s), attached keys([zoo2 zoo1])

# if the lease has expired or does not exist it will give the below response:
Error:  etcdserver: requested lease not found

4 - Зачем нужен шлюз gRPC

etcd v3 использует gRPC как протокол обмена сообщениями. Проект etcd включает основанный на gRPC клиент Go и утилиту командной строки etcdctl для взаимодействия с кластером etcd через gRPC. Для языков без поддержки gRPC etcd предоставляет JSON-шлюз gRPC . Он служит RESTful-прокси, преобразующим запросы HTTP/JSON в сообщения gRPC.

Использование шлюза gRPC

Шлюз принимает JSON-сопоставление определений сообщений protocol buffer etcd. Поля key и value определены как массивы байтов, поэтому в JSON их обязательно кодировать в base64. В следующих примерах используется curl, но подойдёт любой клиент HTTP/JSON.

Примечания

Конечная точка шлюза gRPC менялась начиная с etcd v3.3:

• etcd v3.2 и более ранние версии используют только [CLIENT-URL]/v3alpha/*.
• etcd v3.3 использует [CLIENT-URL]/v3beta/*, сохраняя [CLIENT-URL]/v3alpha/*.
• etcd v3.4 использует [CLIENT-URL]/v3/*, сохраняя [CLIENT-URL]/v3beta/*.
  • [CLIENT-URL]/v3alpha/* устарел.
• etcd v3.5 и более поздние версии используют только [CLIENT-URL]/v3/*.
  • [CLIENT-URL]/v3beta/* устарел.

gRPC-gateway не поддерживает аутентификацию по Common Name сертификата TLS.

Запись и получение ключей

Для чтения и записи ключей используйте службы /v3/kv/range и /v3/kv/put:

<<COMMENT
https://www.base64encode.org/
foo is 'Zm9v' in Base64
bar is 'YmFy'
COMMENT

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"}}

curl -L http://localhost:2379/v3/kv/range \
  -X POST -d '{"key": "Zm9v"}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}

# get all keys prefixed with "foo"
curl -L http://localhost:2379/v3/kv/range \
  -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}

Наблюдение за ключами

Для наблюдения за ключами используйте службу /v3/watch:

curl -N http://localhost:2379/v3/watch \
  -X POST -d '{"create_request": {"key":"Zm9v"} }' &
# {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"1","raft_term":"2"},"created":true}}

curl -L http://localhost:2379/v3/kv/put \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1
# {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"2"},"events":[{"kv":{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}}]}}

Транзакции

Выполните транзакцию через /v3/kv/txn:

# target CREATE
curl -L http://localhost:2379/v3/kv/txn \
  -X POST \
  -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}'
# {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"3","raft_term":"2"},"succeeded":true,"responses":[{"response_put":{"header":{"revision":"3"}}}]}

# target VERSION
curl -L http://localhost:2379/v3/kv/txn \
  -X POST \
  -d '{"compare":[{"version":"4","result":"EQUAL","target":"VERSION","key":"Zm9v"}],"success":[{"requestRange":{"key":"Zm9v"}}]}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"6","raft_term":"3"},"succeeded":true,"responses":[{"response_range":{"header":{"revision":"6"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"6","version":"4","value":"YmF6"}],"count":"1"}}]}

Аутентификация

Настройте аутентификацию с помощью службы /v3/auth:

# create root user
curl -L http://localhost:2379/v3/auth/user/add \
  -X POST -d '{"name": "root", "password": "pass"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# create root role
curl -L http://localhost:2379/v3/auth/role/add \
  -X POST -d '{"name": "root"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# grant root role
curl -L http://localhost:2379/v3/auth/user/grant \
  -X POST -d '{"user": "root", "role": "root"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

# enable auth
curl -L http://localhost:2379/v3/auth/enable -X POST -d '{}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}

Получите токен аутентификации etcd через /v3/auth/authenticate:

# get the auth token for the root user
curl -L http://localhost:2379/v3/auth/authenticate \
  -X POST -d '{"name": "root", "password": "pass"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"},"token":"sssvIpwfnLAcWAQH.9"}

Чтобы получить ключ с учётными данными аутентификации, задайте токен в заголовке Authorization:

curl -L http://localhost:2379/v3/kv/put \
  -H 'Authorization: sssvIpwfnLAcWAQH.9' \
  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"2","raft_term":"2"}}

Ответы об ошибках

Шлюз gRPC преобразует статус gRPC в код состояния HTTP и тело ошибки JSON. Начиная с etcd v3.6, обновление до grpc-gateway v2 изменило обработку ошибок (см. примечание об обработке ошибок в руководстве по миграции на v2), и теперь поведение шлюза соответствует google.rpc.Status (code, message, details), как описано в модели ошибок API Google . В старых версиях grpc-gateway также присутствовало поле верхнего уровня error, но etcd v3.6 и более новые версии его не поддерживают.

Клиентам следует считать код состояния HTTP главным признаком успеха или ошибки. При ошибке запроса основным источником сведений должно быть поле message, а дополнительные данные следует использовать как контекст.

Swagger

Сгенерированные определения API Swagger находятся в rpc.swagger.json .

5 - Именование и обнаружение gRPC

etcd предоставляет резолвер gRPC для альтернативной системы имён, которая получает конечные точки из etcd при обнаружении служб gRPC. Механизм основан на наблюдении за обновлениями ключей с префиксом имени службы.

Эта возможность является экспериментальной, поскольку зависит от пакета google.golang.org/grpc/resolver , который всё ещё считается экспериментальным в grpc-go.

Использование обнаружения etcd с go-grpc

Клиент etcd предоставляет резолвер gRPC для разрешения конечных точек gRPC с бэкендом etcd. Резолвер инициализируется клиентом etcd:

import (
	clientv3 "go.etcd.io/etcd/client/v3"
	etcdnaming "go.etcd.io/etcd/client/v3/naming/resolver"

	"google.golang.org/grpc"
)

...

cli, err := clientv3.NewFromURL("http://localhost:2379")
if err != nil {
    // ...
}
r, err := etcdnaming.NewBuilder(cli)
if err != nil {
    // ...
}
conn, gerr := grpc.NewClient("my-service", grpc.WithResolvers(r), ...)

Управление конечными точками службы

Резолвер etcd рассматривает как потенциальные конечные точки службы все ключи под префиксом целевого имени с завершающим “/” (например, “foo/bar/my-service/”), значения которых закодированы в JSON (исторически — go-grpc naming.Update). Конечные точки добавляются созданием новых ключей и удаляются удалением ключей.

Добавление конечной точки

Новые конечные точки можно добавить в службу с помощью etcdctl:

ETCDCTL_API=3 etcdctl put foo/bar/my-service/1.2.3.4 '{"Addr":"1.2.3.4"}'

Метод endpoints.Manager клиента etcd также может зарегистрировать новую конечную точку с ключом, соответствующим Addr:

em := endpoints.NewManager(client, "foo/bar/my-service")
err := em.AddEndpoint(context.TODO(),"foo/bar/my-service/e1", endpoints.Endpoint{Addr:"1.2.3.4"})

Чтобы включить циклическую балансировку нагрузки при подключении к службе с несколькими конечными точками, настройте соединение с внутренним циклическим балансировщиком gRPC:

conn, gerr := grpc.NewClient("etcd:///foo", grpc.WithResolvers(etcdResolver),
grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`))

Удаление конечной точки

Узлы можно удалить из службы с помощью etcdctl:

ETCDCTL_API=3 etcdctl del foo/bar/my-service/1.2.3.4

Метод endpoints.Manager клиента etcd также поддерживает удаление конечных точек:

em := endpoints.NewManager(client, "foo/bar/my-service")
err := em.DeleteEndpoint(context.TODO(), "foo/bar/my-service/e1")

Регистрация конечной точки с арендой

Регистрация конечной точки с арендой гарантирует её удаление из службы, если узел не сможет поддерживать heartbeat keepalive, например из-за отказа машины:

lease=`ETCDCTL_API=3 etcdctl lease grant 5 | cut -f2 -d' '`
ETCDCTL_API=3 etcdctl put --lease=$lease my-service/1.2.3.4 '{"Addr":"1.2.3.4"}'
ETCDCTL_API=3 etcdctl lease keep-alive $lease

В Golang:

em := endpoints.NewManager(client, "foo/bar/my-service")
err := em.AddEndpoint(context.TODO(), "foo/bar/my-service/e1", endpoints.Endpoint{Addr:"1.2.3.4"})

Атомарное обновление конечных точек

Чтобы изменить несколько конечных точек в одной транзакции, можно напрямую использовать endpoints.Manager:

em := endpoints.NewManager(c, "foo")

err := em.Update(context.TODO(), []*endpoints.UpdateWithOpts{
    endpoints.NewDeleteUpdateOpts("foo/bar/my-service/e1", endpoints.Endpoint{Addr: "1.2.3.4"}),
	endpoints.NewAddUpdateOpts("foo/bar/my-service/e1", endpoints.Endpoint{Addr: "1.2.3.14"})})

6 - Встраивание etcd в Go-приложение

Пакет go etcd embed предоставляет простой способ встраивания сервера etcd непосредственно в ваше приложение.

Дополнительные сведения см. в документации пакета embed .

7 - Ограничения системы

Ограничение размера запроса

etcd разработан для обработки небольших пар ключ-значение, характерных для метаданных. Более крупные запросы будут работать, но могут увеличить задержку других запросов. По умолчанию максимальный размер любого запроса составляет 1.5 MiB. Этот лимит можно настроить с помощью флага --max-request-bytes для сервера etcd.

Ограничение размера хранилища

По умолчанию ограничение размера хранилища составляет 2 GiB, настраивается с помощью флага --quota-backend-bytes. 8 GiB — рекомендуемый максимальный размер для обычных сред, etcd выдает предупреждение при запуске, если сконфигурированное значение превышает его.

8 - Возможности etcd

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

Возможности etcd проходят три стадии: экспериментальную, стабильную и небезопасную. Получить их список можно командой etcd --help.

Экспериментальные

Чтобы получить обратную связь на раннем этапе, новые возможности обычно добавляются как экспериментальные. Их можно определить по имени флага с префиксом --experimental. При использовании экспериментальной возможности учитывайте следующее:

• Из-за недостаточного пользовательского тестирования она может содержать ошибки и работать не так, как ожидается.
• По умолчанию она отключена.
• Её поддержка может быть прекращена в любой момент без уведомления.
  • Возможность может быть удалена в следующем минорном или мажорном выпуске без соблюдения политики устаревания возможностей , если она не перейдёт в стабильную стадию.
  • Команда проекта приветствует сообщения о проблемах с экспериментальными возможностями, однако такие проблемы могут иметь более низкий приоритет, чем проблемы стабильных возможностей.
• Экспериментальный флаг возможности устаревает при переходе в стабильную стадию. Следует как можно раньше перейти на стабильный флаг.

Стабильные

Это наиболее распространённая стадия возможностей etcd. Стабильная возможность обладает следующими свойствами:

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

Небезопасные

Небезопасные возможности встречаются редко и перечисляются в разделе Unsafe feature: документации по использованию etcd. По умолчанию они отключены. Используйте их с осторожностью и в соответствии с документацией. Небезопасная возможность может быть удалена в следующем минорном или мажорном выпуске без соблюдения политики устаревания.

Устаревание возможностей

Экспериментальные

Экспериментальная возможность устаревает при переходе в стабильную стадию.

• В документации экспериментальной возможности появляется сообщение об устаревании с рекомендацией использовать соответствующий стабильный флаг, например DEPRECATED. Use <feature-name> instead.
• Устаревшая возможность удаляется в следующем выпуске.

Стабильные

По мере развития проекта стабильную возможность иногда приходится объявлять устаревшей и удалять. В таком случае:

• До запланированного выпуска с объявлением об устаревании в документации появляется предупреждение, например To be deprecated in <release>.. Если уже запланирована замена возможности, помеченной To be deprecated, документация также указывает её, например Use <feature-name> instead..
• В запланированном выпуске возможность объявляется устаревшей. В документации появляется соответствующее сообщение с рекомендацией использовать связанную стабильную возможность, например DEPRECATED. Use <feature-name> instead.
• Устаревшая возможность удаляется в следующем выпуске.

9 - Справочник API

Этот справочник API автоматически создан из указанных файлов .proto.

Служба Auth (api/etcdserverpb/rpc.proto)

Служба Cluster (api/etcdserverpb/rpc.proto)

Служба KV (api/etcdserverpb/rpc.proto)

Служба Lease (api/etcdserverpb/rpc.proto)

Служба Maintenance (api/etcdserverpb/rpc.proto)

Служба Watch (api/etcdserverpb/rpc.proto)

Сообщение AlarmMember (api/etcdserverpb/rpc.proto)

Сообщение AlarmRequest (api/etcdserverpb/rpc.proto)

Сообщение AlarmResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthDisableRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthDisableResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthEnableRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthEnableResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleAddRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleAddResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleDeleteRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleDeleteResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleGetRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleGetResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleGrantPermissionRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleGrantPermissionResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleListRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleListResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleRevokePermissionRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthRoleRevokePermissionResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthStatusRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthStatusResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthUserAddRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthUserAddResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthUserChangePasswordRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthUserChangePasswordResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthUserDeleteRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthUserDeleteResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthUserGetRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthUserGetResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthUserGrantRoleRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthUserGrantRoleResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthUserListRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthUserListResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthUserRevokeRoleRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthUserRevokeRoleResponse (api/etcdserverpb/rpc.proto)

Сообщение AuthenticateRequest (api/etcdserverpb/rpc.proto)

Сообщение AuthenticateResponse (api/etcdserverpb/rpc.proto)

Сообщение CompactionRequest (api/etcdserverpb/rpc.proto)

CompactionRequest компактизирует хранилище ключей и значений до заданной ревизии. Все замещённые ключи с ревизией меньше ревизии компактизации удаляются.

Сообщение CompactionResponse (api/etcdserverpb/rpc.proto)

Сообщение Compare (api/etcdserverpb/rpc.proto)

Сообщение DefragmentRequest (api/etcdserverpb/rpc.proto)

Сообщение DefragmentResponse (api/etcdserverpb/rpc.proto)

Сообщение DeleteRangeRequest (api/etcdserverpb/rpc.proto)

Сообщение DeleteRangeResponse (api/etcdserverpb/rpc.proto)

Сообщение DowngradeInfo (api/etcdserverpb/rpc.proto)

Сообщение DowngradeRequest (api/etcdserverpb/rpc.proto)

Сообщение DowngradeResponse (api/etcdserverpb/rpc.proto)

Сообщение DowngradeVersionTestRequest (api/etcdserverpb/rpc.proto)

DowngradeVersionTestRequest используется только для тестирования. Версия в запросе читается как версия записи WAL. Если целевая версия понижения меньше этой версии, понижение (online) или миграция (offline) небезопасны и не должны разрешаться.

Сообщение HashKVRequest (api/etcdserverpb/rpc.proto)

Сообщение HashKVResponse (api/etcdserverpb/rpc.proto)

Сообщение HashRequest (api/etcdserverpb/rpc.proto)

Сообщение HashResponse (api/etcdserverpb/rpc.proto)

Сообщение LeaseCheckpoint (api/etcdserverpb/rpc.proto)

Сообщение LeaseCheckpointRequest (api/etcdserverpb/rpc.proto)

Сообщение LeaseCheckpointResponse (api/etcdserverpb/rpc.proto)

Сообщение LeaseGrantRequest (api/etcdserverpb/rpc.proto)

Сообщение LeaseGrantResponse (api/etcdserverpb/rpc.proto)

Сообщение LeaseKeepAliveRequest (api/etcdserverpb/rpc.proto)

Сообщение LeaseKeepAliveResponse (api/etcdserverpb/rpc.proto)

Сообщение LeaseLeasesRequest (api/etcdserverpb/rpc.proto)

Сообщение LeaseLeasesResponse (api/etcdserverpb/rpc.proto)

Сообщение LeaseRevokeRequest (api/etcdserverpb/rpc.proto)

Сообщение LeaseRevokeResponse (api/etcdserverpb/rpc.proto)

Сообщение LeaseStatus (api/etcdserverpb/rpc.proto)

Сообщение LeaseTimeToLiveRequest (api/etcdserverpb/rpc.proto)

Сообщение LeaseTimeToLiveResponse (api/etcdserverpb/rpc.proto)

Сообщение Member (api/etcdserverpb/rpc.proto)

Сообщение MemberAddRequest (api/etcdserverpb/rpc.proto)

Сообщение MemberAddResponse (api/etcdserverpb/rpc.proto)

Сообщение MemberListRequest (api/etcdserverpb/rpc.proto)

Сообщение MemberListResponse (api/etcdserverpb/rpc.proto)

Сообщение MemberPromoteRequest (api/etcdserverpb/rpc.proto)

Сообщение MemberPromoteResponse (api/etcdserverpb/rpc.proto)

Сообщение MemberRemoveRequest (api/etcdserverpb/rpc.proto)

Сообщение MemberRemoveResponse (api/etcdserverpb/rpc.proto)

Сообщение MemberUpdateRequest (api/etcdserverpb/rpc.proto)

Сообщение MemberUpdateResponse (api/etcdserverpb/rpc.proto)

Сообщение MoveLeaderRequest (api/etcdserverpb/rpc.proto)

Сообщение MoveLeaderResponse (api/etcdserverpb/rpc.proto)

Сообщение PutRequest (api/etcdserverpb/rpc.proto)

Сообщение PutResponse (api/etcdserverpb/rpc.proto)

Сообщение RangeRequest (api/etcdserverpb/rpc.proto)

Сообщение RangeResponse (api/etcdserverpb/rpc.proto)

Сообщение RequestOp (api/etcdserverpb/rpc.proto)

Сообщение ResponseHeader (api/etcdserverpb/rpc.proto)

Сообщение ResponseOp (api/etcdserverpb/rpc.proto)

Сообщение SnapshotRequest (api/etcdserverpb/rpc.proto)

Сообщение SnapshotResponse (api/etcdserverpb/rpc.proto)

Сообщение StatusRequest (api/etcdserverpb/rpc.proto)

Сообщение StatusResponse (api/etcdserverpb/rpc.proto)

Сообщение TxnRequest (api/etcdserverpb/rpc.proto)

Из статьи Google о paxosdb: наша реализация строится вокруг мощного примитива MultiOp. Все остальные операции с базой данных, кроме итерации, реализованы как один вызов MultiOp. MultiOp применяется атомарно и состоит из трёх компонентов: 1. Список проверок guard. Каждая проверка guard проверяет одну запись базы данных: отсутствие или наличие значения либо равенство заданному значению. Две проверки guard могут относиться к одной или разным записям. Все проверки guard применяются, и MultiOp возвращает результаты. Если все проверки истинны, MultiOp выполняет t op (см. пункт 2 ниже), иначе — f op (см. пункт 3 ниже). 2. Список операций базы данных t op. Каждая операция списка является вставкой, удалением или поиском и применяется к одной записи. Две операции могут относиться к одной или разным записям. Они выполняются, если guard истинно. 3. Список операций базы данных f op. Аналогичен t op, но выполняется, если guard ложно.

Сообщение TxnResponse (api/etcdserverpb/rpc.proto)

Сообщение WatchCancelRequest (api/etcdserverpb/rpc.proto)

Сообщение WatchCreateRequest (api/etcdserverpb/rpc.proto)

Сообщение WatchProgressRequest (api/etcdserverpb/rpc.proto)

Запрашивает как можно скорее отправить состояние прогресса потока наблюдения в потоке ответов наблюдения.

Сообщение WatchRequest (api/etcdserverpb/rpc.proto)

Сообщение WatchResponse (api/etcdserverpb/rpc.proto)

Сообщение Event (api/mvccpb/kv.proto)

Сообщение KeyValue (api/mvccpb/kv.proto)

Сообщение Lease (server/lease/leasepb/lease.proto)

Сообщение LeaseInternalRequest (server/lease/leasepb/lease.proto)

Сообщение LeaseInternalResponse (server/lease/leasepb/lease.proto)

Сообщение Permission (api/authpb/auth.proto)

Permission — отдельная сущность

Сообщение Role (api/authpb/auth.proto)

Role — отдельная запись в сегменте authRoles

Сообщение User (api/authpb/auth.proto)

User — отдельная запись в сегменте authUsers

Сообщение UserAddOptions (api/authpb/auth.proto)

10 - Справочник API: конкурентность

Этот справочник API автоматически создан из указанных файлов .proto.

служба Lock (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

Служба блокировок предоставляет клиентские средства блокировки через интерфейс gRPC.

сообщение LockRequest (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

сообщение LockResponse (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

сообщение UnlockRequest (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

сообщение UnlockResponse (server/etcdserver/api/v3lock/v3lockpb/v3lock.proto)

служба Election (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

Служба выборов предоставляет клиентские средства выборов через интерфейс gRPC.

сообщение CampaignRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение CampaignResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение LeaderKey (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение LeaderRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение LeaderResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение ProclaimRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение ProclaimResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение ResignRequest (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение ResignResponse (server/etcdserver/api/v3election/v3electionpb/v3election.proto)

сообщение Event (api/mvccpb/kv.proto)

сообщение KeyValue (api/mvccpb/kv.proto)