Эта секция содержит руководства, ориентированные на выполнение задач, для разработчиков, строящих приложения с использованием etcd, и для операторов, ответственных за развертывание, настройку и поддержку кластеров etcd.
Теперь etcd готов к работе! Для подключения к etcd с помощью etcdctl выполните:
exportETCDCTL_API=3HOST_1=10.240.0.17
HOST_2=10.240.0.18
HOST_3=10.240.0.19
ENDPOINTS=$HOST_1:2379,$HOST_2:2379,$HOST_3:2379
etcdctl --endpoints=$ENDPOINTS member list
1.2 - Как проводить выборы лидера в кластере etcd
Шаги проведения выборов лидера с помощью клиента etcdctl
Команда etcdctl используется для проведения выборов лидера в кластере etcd. Она гарантирует, что в один момент времени только один клиент может стать лидером.
Затем замените участника командами member remove и member add:
# get member IDexportETCDCTL_API=3HOST_1=10.240.0.13
HOST_2=10.240.0.14
HOST_3=10.240.0.15
etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379,${HOST_3}:2379 member list
# remove the memberMEMBER_ID=278c654c9a6dfd3b
etcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379,${HOST_3}:2379 \
member remove ${MEMBER_ID}# add a new member (node 4)exportETCDCTL_API=3NAME_1=etcd-node-1
NAME_2=etcd-node-2
NAME_4=etcd-node-4
HOST_1=10.240.0.13
HOST_2=10.240.0.14
HOST_4=10.240.0.16 # new memberetcdctl --endpoints=${HOST_1}:2379,${HOST_2}:2379 \
member add ${NAME_4}\
--peer-urls=http://${HOST_4}:2380
После этого запустите нового участника с флагом --initial-cluster-state existing:
# [WARNING] If the new member starts from the same disk space,# make sure to remove the data directory of the old member## restart with 'existing' flagTOKEN=my-etcd-token-1
CLUSTER_STATE=existing
NAME_1=etcd-node-1
NAME_2=etcd-node-2
NAME_4=etcd-node-4
HOST_1=10.240.0.13
HOST_2=10.240.0.14
HOST_4=10.240.0.16 # new memberCLUSTER=${NAME_1}=http://${HOST_1}:2380,${NAME_2}=http://${HOST_2}:2380,${NAME_4}=http://${HOST_4}:2380
THIS_NAME=${NAME_4}THIS_IP=${HOST_4}etcd --data-dir=data.etcd --name ${THIS_NAME}\
--initial-advertise-peer-urls http://${THIS_IP}:2380 \
--listen-peer-urls http://${THIS_IP}:2380 \
--advertise-client-urls http://${THIS_IP}:2379 \
--listen-client-urls http://${THIS_IP}:2379 \
--initial-cluster ${CLUSTER}\
--initial-cluster-state ${CLUSTER_STATE}\
--initial-cluster-token ${TOKEN}
2 - Задачи разработчика
Пошаговые инструкции для разработчиков, использующих etcd как хранилище ключей-значений в своих приложениях.
2.1 - Чтение из etcd
Чтение значения в кластере etcd
Предварительные требования
Установите etcdctl
Процедура
Используйте подкоманду get для чтения из etcd:
$ etcdctl --endpoints=$ENDPOINTS get foo
foo
Hello World!
$
где:
foo — запрашиваемый ключ
Hello World! — полученное значение
Или для форматированного вывода:
$ etcdctl --endpoints=$ENDPOINTS --write-out="json" get foo
{"header":{"cluster_id":289318470931837780,"member_id":14947050114012957595,"revision":3,"raft_term":4,
"kvs":[{"key":"Zm9v","create_revision":2,"mod_revision":3,"version":2,"value":"SGVsbG8gV29ybGQh"}]}}
$
где write-out="json" заставляет выводить значение в формате JSON (обратите внимание, ключ не возвращается).
2.2 - Запись в etcd
Добавление пары ключ-значение в кластер etcd
Предварительные условия
Установите etcdctl
Процедура
Используйте подкоманду put для записи пары «ключ — значение»:
etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"
где:
foo — имя ключа
"Hello World!" — значение, заключённое в кавычки
2.3 - Как получить ключи по префиксу
Руководство по извлечению ключей etcd по их префиксу
$ etcdctl --endpoints=$ENDPOINTS get PREFIX --prefix
Глобальные параметры
--endpoints=[127.0.0.1:2379], gRPC endpoints
Параметры
--prefix, get a range of keys with matching prefix
Пример
etcdctl --endpoints=$ENDPOINTS put web1 value1
etcdctl --endpoints=$ENDPOINTS put web2 value2
etcdctl --endpoints=$ENDPOINTS put web3 value3
etcdctl --endpoints=$ENDPOINTS get web --prefix
del для удаления указанного ключа или диапазона ключей:
etcdctl del $KEY[$END_KEY]
Параметры
--prefix[=false]: delete keys with matching prefix
--prev-kv[=false]: return deleted key-value pairs
--from-key[=false]: delete keys that are greater than or equal to the given key using byte compare
--range[=false]: delete range of keys without delay
Параметры, унаследованные от родительских команд
--endpoints="127.0.0.1:2379": gRPC endpoints
Примеры
etcdctl --endpoints=$ENDPOINTS put key myvalue
etcdctl --endpoints=$ENDPOINTS del key
etcdctl --endpoints=$ENDPOINTS put k1 value1
etcdctl --endpoints=$ENDPOINTS put k2 value2
etcdctl --endpoints=$ENDPOINTS del k --prefix
2.5 - Как выполнить несколько записей в транзакции
Название команды txn сокращает слово «transaction». Она читает несколько запросов etcd из стандартного ввода и применяет их как одну атомарную транзакцию. Транзакция состоит из списка условий, списка запросов, выполняемых при истинности всех условий, и списка запросов, выполняемых при ложности любого условия. Дополнительные сведения приведены в разделе команд etcdctl для ключей и значений
.
compare
Секция compare в транзакции (txn) выполняет условную проверку и определяет, следует ли выполнять операции транзакции. Изменения применяются только тогда, когда текущее состояние хранилища ключей и значений соответствует ожидаемым условиям. Это сохраняет согласованность данных и предотвращает конфликты при параллельной работе. Структура команды показана ниже в разделе Выполнение транзакции
.
Транзакции
Команда txn обрабатывает все запросы в одной транзакции:
etcdctl txn --help
Транзакции etcd позволяют атомарно выполнить несколько операций: либо применяются все операции, либо не применяется ни одна. Это необходимо для сохранения согласованности данных при связанных обновлениях. Подробнее см. в документации API
.
Пример
Рассмотрим обновление адреса электронной почты и номера телефона пользователя в одной транзакции. Оба изменения будут применены совместно.
0. Используемые переменные и флаги
Переменные
/users/{<user_id>/email : ключ etcd, представляющий адрес электронной почты пользователя.
/users/<user_id>/phone : ключ etcd, представляющий номер телефона пользователя.
Флаги
--interactive
: флаг, разрешающий вводить данные транзакции вручную
1. Создание исходных данных
Сначала создайте пользователя с исходными данными.
etcdctl put /users/12345/email "old.address@johndoe.com"etcdctl put /users/12345/phone "123-456-7890"
2. Выполнение транзакции
Обновите адрес электронной почты и номер телефона пользователя в одной транзакции.
etcdctl txn --interactive
compares:
value("/users/12345/email")="old.address@johndoe.com"success requests (get, put, delete):
put /users/12345/email "new.address@johndoe.com"put /users/12345/phone "098-765-4321"failure requests (get, put, delete):
get /users/12345/email
Сравнение: проверьте, что текущий адрес равен «old.address@johndoe.com
». Транзакция продолжится только при ожидаемом состоянии данных.
Успех: если сравнение истинно, обновите и адрес электронной почты, и номер телефона.
Неудача: если сравнение ложно, получите текущий адрес, чтобы выяснить, почему транзакция не была выполнена.
Важные соображения
Атомарность: транзакция гарантирует совместное обновление адреса электронной почты и номера телефона. Если исходное условие сравнения не выполнено, ни одно обновление не применяется.
Согласованность: транзакции сохраняют согласованность данных, особенно при нескольких связанных обновлениях.
Не записывайте один ключ несколько раз: не присваивайте одному ключу несколько значений в одной транзакции, поскольку это может привести к неожиданным результатам. Каждый ключ следует обновлять только один раз за транзакцию.
watch для получения уведомлений о будущих изменениях:
etcdctl watch $KEY[$END_KEY]
Параметры
-i, --interactive[=false]: interactive mode
--prefix[=false]: watch on a prefix if prefix is set--rev=0: Revision to start watching
--prev-kv[=false]: get the previous key-value pair before the event happens
--progress-notify[=false]: get periodic watch progress notification from server
Параметры, унаследованные от родительских команд
--endpoints="127.0.0.1:2379": gRPC endpoints
Примеры
etcdctl --endpoints=$ENDPOINTS watch stock1
etcdctl --endpoints=$ENDPOINTS put stock1 1000etcdctl --endpoints=$ENDPOINTS watch stock --prefix
etcdctl --endpoints=$ENDPOINTS put stock1 10etcdctl --endpoints=$ENDPOINTS put stock2 20
2.7 - Как создать аренду
Руководство по созданию аренды в etcd
lease записывать с TTL:
etcdctl --endpoints=$ENDPOINTS lease grant 300# lease 2be7547fbc6a5afa granted with TTL(300s)etcdctl --endpoints=$ENDPOINTS put sample value --lease=2be7547fbc6a5afa
etcdctl --endpoints=$ENDPOINTS get sample
etcdctl --endpoints=$ENDPOINTS lease keep-alive 2be7547fbc6a5afa
etcdctl --endpoints=$ENDPOINTS lease revoke 2be7547fbc6a5afa
# or after 300 secondsetcdctl --endpoints=$ENDPOINTS get sample
2.8 - Как создавать блокировки
Руководство по созданию распределенных блокировок в etcd
LOCK приобретает распределённый мьютекс с указанным именем. Как только блокировка будет получена, она будет удерживаться до завершения работы etcdctl.
