Это многостраничная версия текущего раздела для печати. .

Задачи разработчика

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

1: Чтение из etcd
2: Запись в etcd
3: Как получить ключи по префиксу
4: Как удалить ключи
5: Как выполнить несколько записей в транзакции
6: Как наблюдать за ключами
7: Как создать аренду
8: Как создавать блокировки

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 - Запись в etcd

Добавление пары ключ-значение в кластер etcd

Предварительные условия

Установите etcdctl

Процедура

Используйте подкоманду put для записи пары «ключ — значение»:

etcdctl --endpoints=$ENDPOINTS put foo "Hello World!"

где:

foo — имя ключа
"Hello World!" — значение, заключённое в кавычки

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

4 - Как удалить ключи

Описывает способ удаления ключей etcd

Предварительные требования

Установите etcd и etcdctl

Добавление или удаление ключей

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

5 - Как выполнить несколько записей в транзакции

Руководство по транзакционной записи

Предварительные условия

Установите etcd и etcdctl .
Работающий кластер etcd.

Терминология

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

Термин	Определение
etcdctl	Инструмент командной строки для взаимодействия с сервером etcd.
Команда `txn`	Название команды `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 ». Транзакция продолжится только при ожидаемом состоянии данных.
Успех: если сравнение истинно, обновите и адрес электронной почты, и номер телефона.
Неудача: если сравнение ложно, получите текущий адрес, чтобы выяснить, почему транзакция не была выполнена.

Важные соображения

Атомарность: транзакция гарантирует совместное обновление адреса электронной почты и номера телефона. Если исходное условие сравнения не выполнено, ни одно обновление не применяется.
Согласованность: транзакции сохраняют согласованность данных, особенно при нескольких связанных обновлениях.
Не записывайте один ключ несколько раз: не присваивайте одному ключу несколько значений в одной транзакции, поскольку это может привести к неожиданным результатам. Каждый ключ следует обновлять только один раз за транзакцию.

6 - Как наблюдать за ключами

Руководство по наблюдению за ключами etcd

Предварительные требования

Установите etcd и etcdctl

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

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 1000

etcdctl --endpoints=$ENDPOINTS watch stock --prefix
etcdctl --endpoints=$ENDPOINTS put stock1 10
etcdctl --endpoints=$ENDPOINTS put stock2 20

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 seconds
etcdctl --endpoints=$ENDPOINTS get sample

8 - Как создавать блокировки

Руководство по созданию распределенных блокировок в etcd

LOCK приобретает распределённый мьютекс с указанным именем. Как только блокировка будет получена, она будет удерживаться до завершения работы etcdctl.

Предварительные требования

Установите etcd и etcdctl

Создание блокировки

lock для распределённой блокировки:

etcdctl --endpoints=$ENDPOINTS lock mutex1

Параметры

endpoints — определяет список адресов машин в кластере, разделённых запятыми.
ttl — время ожидания в секундах сессии блокировки.