Как использовать Etcdctl и Etcd, распределенное хранилище ключей-значений CoreOS

Вступление

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

В этом руководстве мы рассмотрим демон + etcd +, а также утилиту + etcdctl + и HTTP / JSON API, которые можно использовать для управления им.

Предпосылки

Чтобы следовать этому руководству, мы предполагаем, что у вас есть кластер машин CoreOS в качестве нашего руководства на https://www.digitalocean.com/community/tutorials/how-to-set-up-a-coreos-cluster-on -digitalocean [настройка кластера CoreOS на DigitalOcean] обрисовывает в общих чертах. Это оставит вас с тремя серверами в одном кластере:

coreos-1
coreos-2
coreos-3

После того, как вы запустите эти машины, вы можете продолжить работу с этим руководством.

Модель обнаружения кластеров Etcd

Одной из самых фундаментальных задач, за которые отвечает + etcd +, является организация отдельных машин в кластер. Это делается при загрузке CoreOS путем регистрации по адресу обнаружения, указанному в файле + cloud-config +, который передается при создании.

Служба обнаружения, запущенная CoreOS, доступна по адресу + https: // discovery.etcd.io +. Вы можете получить новый токен, посетив страницу + / new +. Там вы получите токен, который ваши машины смогут использовать для обнаружения своих сопутствующих узлов. Это будет выглядеть примерно так:

https://discovery.etcd.io/

Вы должны предоставить свежий токен для каждого нового кластера. Это включает в себя, когда вам нужно перестроить кластер, используя узлы, которые могут иметь одинаковый IP-адрес. Экземпляры + etcd + будут сбиты с толку и не будут правильно работать для построения кластера, если вы повторно используете адрес обнаружения.

Зайдя по адресу обнаружения в вашем веб-браузере, вы получите объект JSON, который описывает известные машины. Это не будет никаких узлов, когда вы начинаете:

{"action":"get","node":{"key":"/_etcd/registry/dcadc5d4d42328488ecdcd7afae5f57c","dir":true,"modifiedIndex":102511104,"createdIndex":102511104}}

После начальной загрузки вашего кластера вы сможете увидеть больше информации здесь:

{"action":"get","node":{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda","dir":true,"nodes":[{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda/2ddbdb7c872b4bc59dd1969ac166501e","value":"http://10.132.252.38:7001","expiration":"2014-09-19T13:41:26.912303668Z","ttl":598881,"modifiedIndex":102453704,"createdIndex":102453704},{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda/921a7241c31a499a97d43f785108b17c","value":"http://10.132.248.118:7001","expiration":"2014-09-19T13:41:29.602508981Z","ttl":598884,"modifiedIndex":102453736,"createdIndex":102453736},{"key":"/_etcd/registry/1edee33e6b03e75d9428eacf0ff94fda/27987f5eaac243f88ca6823b47012c5b","value":"http://10.132.248.121:7001","expiration":"2014-09-19T13:41:41.817958205Z","ttl":598896,"modifiedIndex":102453860,"createdIndex":102453860}],"modifiedIndex":101632353,"createdIndex":101632353}}

Если вам нужно найти URL-адрес обнаружения кластера, вы можете сделать это с любого из компьютеров, которые являются его членами. Эту информацию можно получить из иерархии + / run +:

cat /run/systemd/system/etcd.service.d/20-cloudinit.conf

[Service]
Environment="ETCD_ADDR=10.132.248.118:4001"
Environment="ETCD_DISCOVERY=https://discovery.etcd.io/dcadc5d4d42328488ecdcd7afae5f57c"
Environment="ETCD_NAME=921a7241c31a499a97d43f785108b17c"
Environment="ETCD_PEER_ADDR=10.132.248.118:7001"

URL хранится в записи + ETCD_DISCOVERY +.

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

Последующие машины также свяжутся с URL-адресом обнаружения со своей информацией. Они получат информацию о машинах, которые уже зарегистрировались. Затем они выберут одну из этих машин и подключатся напрямую, где они получат полный список исправных членов кластера. Репликация и распространение данных осуществляется через консенсусный алгоритм Raft.

Данные о каждой из машин хранятся в скрытой структуре каталогов внутри + etcd +. Вы можете увидеть информацию о машинах, о которых знает + etcd +, набрав:

etcdctl ls /_etcd/machines --recursive

/_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e
/_etcd/machines/921a7241c31a499a97d43f785108b17c
/_etcd/machines/27987f5eaac243f88ca6823b47012c5b

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

etcdctl get /_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e

etcd=http%3A%2F%2F10.132.252.38%3A4001&raft=http%3A%2F%2F10.132.252.38%3A7001

Далее мы рассмотрим команды + etcdctl + более подробно.

Etcdctl Использование

Существует два основных способа взаимодействия с + etcd +. Через HTTP / JSON API и через клиента, например, включенную утилиту + etcdctl +. Сначала мы рассмотрим + etcdctl +.

Просмотр ключей и каталогов

Для начала давайте посмотрим, что в данный момент хранит + etcdctl +. Мы можем увидеть ключи верхнего уровня, набрав:

etcdctl ls /

/coreos.com

Как видите, у нас один результат. На данный момент неясно, является ли это каталог или ключ. Мы можем попытаться + получить + узел, чтобы увидеть либо значение ключа, либо увидеть, что это каталог:

etcdctl get /coreos.com

/coreos.com: is a directory

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

etcdctl ls / --recursive

/coreos.com
/coreos.com/updateengine
/coreos.com/updateengine/rebootlock
/coreos.com/updateengine/rebootlock/semaphore

Как видите, под начальным узлом + / coreos.com + было довольно много каталогов. Мы можем увидеть, как выглядит получение фактических данных из узла, запросив информацию в конечной точке:

etcdctl get /coreos.com/updateengine/rebootlock/semaphore

{"semaphore":1,"max":1,"holders":null}

Это не содержит информацию, которая очень полезна для нас. Мы можем получить некоторые дополнительные метаданные об этой записи, передав опцию + -o extended +. Это глобальная опция, поэтому она должна идти перед командой + get +:

etcdctl -o extended get /coreos.com/updateengine/rebootlock/semaphore

Key: /coreos.com/updateengine/rebootlock/semaphore
Created-Index: 6
Modified-Index: 6
TTL: 0
Etcd-Index: 170387
Raft-Index: 444099
Raft-Term: 8

{"semaphore":1,"max":1,"holders":null}

Настройка ключей и создание узлов

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

etcdctl mkdir /example

Чтобы создать ключ, вы можете использовать команду + mk +:

etcdctl mk /example/key data

data

Это будет работать только в том случае, если ключ еще не существует. Если мы запрашиваем значение ключа, который мы создали, мы можем получить данные, которые мы установили:

etcdctl get /example/key

data

Чтобы обновить существующий ключ, используйте команду + update:

etcdctl update /example/key turtles

turtles

Сопутствующая команда + updatedir + для каталогов, вероятно, полезна, только если вы установили TTL или время жизни в каталоге. Это обновит время TTL с прошедшим. Вы можете установить TTL для каталогов или ключей, передав аргумент + - ttl # +, где «#» - это количество секунд, которое нужно сохранить:

etcdctl mkdir /here/you/go --ttl 120

Затем вы можете обновить TTL с помощью + updatedir +:

etcdctl updatedir /here/you/go --ttl 500

Чтобы изменить значение существующего ключа или создать ключ, если он не существует, используйте команду + set +. Думайте об этом как о комбинации команд + mk + и + update +:

etcdctl set /example/key new

new

Это может включать в себя несуществующие пути. Компоненты пути будут создаваться динамически:

etcdctl set /a/b/c here

here

Чтобы получить такую же функциональность создания, если не существует для каталогов, вы можете использовать команду + setdir +:

etcdctl setdir /x/y/z

Примечание *: команда + setdir + в настоящее время не работает, как указано. В текущей сборке ее использование отражает команду + updatedir + и завершится ошибкой, если каталог уже существует. Существует открытая проблема в репозитории GitHub для решения этой проблемы.

Удаление записей

Чтобы удалить существующие ключи, вы можете использовать команду + rm + или + rmdir +.

Команда + rm + может использоваться для удаления ключа:

etcdctl rm /a/b/c

Он также может быть использован рекурсивно для удаления каталога и каждого подкаталога:

etcdctl rm /a --recursive

Чтобы удалить только пустой каталог _ или_ ключ, используйте команду + rmdir +:

etcdctl rmdir /x/y/z

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

В ожидании перемен

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

Чтобы посмотреть ключ, используйте его без каких-либо флагов:

etcdctl watch /example/hello

Чтобы остановить просмотр, вы можете нажать + CTRL-C +. Если во время просмотра обнаружено изменение, будет возвращено новое значение.

Чтобы просмотреть всю структуру каталогов, используйте флаг + - recursive +:

etcdctl watch --recursive /example

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

while true; do etcdctl watch --recursive /example; done

Если вы хотите выполнить команду при обнаружении изменения, используйте команду + exec-watch +:

etcdctl exec-watch --recursive  /example -- echo "hello"

Это будет отображать «привет» на экране всякий раз, когда значение в этом каталоге изменяется.

Скрытые ценности

Одна вещь, которая не сразу бросается в глаза, это то, что внутри + etcd + есть скрытые структуры каталогов. Это каталоги или ключи, которые начинаются с подчеркивания.

Они не перечислены обычными инструментами + etcdctl +, и вы должны знать, что вы ищете, чтобы найти их.

Например, существует скрытый каталог + / _ coreos.com +, который содержит некоторую внутреннюю информацию о + fleet +. Вы можете увидеть иерархию, явно запросив ее:

etcdctl ls --recursive /_coreos.com

/_coreos.com/fleet
/_coreos.com/fleet/states
/_coreos.com/fleet/states/[email protected]
/_coreos.com/fleet/states/[email protected]/2ddbdb7c872b4bc59dd1969ac166501e
/_coreos.com/fleet/states/[email protected]
/_coreos.com/fleet/states/[email protected]/921a7241c31a499a97d43f785108b17c
. . .

Другая такая структура каталогов находится в + / _ etcd +:

etcdctl ls --recursive /_etcd

/_etcd/machines
/_etcd/machines/27987f5eaac243f88ca6823b47012c5b
/_etcd/machines/2ddbdb7c872b4bc59dd1969ac166501e
/_etcd/machines/921a7241c31a499a97d43f785108b17c
/_etcd/config

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

Etcd HTTP / JSON API Использование

Другой способ взаимодействия с + etcd + - это простой HTTP / JSON API.

Чтобы получить доступ к API, вы можете использовать простую программу HTTP, такую как + curl +. Вы должны предоставить флаг + -L +, чтобы следовать любым перенаправлениям, которые передаются обратно. Внутри вашего кластера вы можете использовать локальный интерфейс + 127.0.0.1 + и порт + 4001 + для большинства запросов.

Примечание *: Для подключения к + etcd + из контейнера Docker можно использовать адрес + http: //172.17.42.1: 4001 +. Это может быть полезно для приложений, чтобы обновить свои конфигурации на основе зарегистрированной информации.

Нормальное пространство ключей можно получить, перейдя в + http: //127.0.0.1: 4001 / v2 / keys / + на любой из хост-машин. Например, чтобы получить список ключей / каталогов верхнего уровня, введите:

curl -L http://127.0.0.1:4001/v2/keys/

{"action":"get","node":{"key":"/","dir":true,"nodes":[{"key":"/coreos.com","dir":true,"modifiedIndex":6,"createdIndex":6},{"key":"/services","dir":true,"modifiedIndex":333,"createdIndex":333}]}}

Конечный слеш в запросе является обязательным. Это не решит правильно без этого.

Вы можете установить или получить значения, используя обычные HTTP-глаголы.

Чтобы изменить поведение этих операций, вы можете передать флаги в конце вашего запроса, используя синтаксис +? Flag = value +. Несколько флагов могут быть разделены символом + & +.

Например, чтобы рекурсивно перечислить все ключи, мы могли бы набрать:

curl -L http://127.0.0.1:4001/v2/keys/?recursive=true

{"action":"get","node":{"key":"/","dir":true,"nodes":[{"key":"/coreos.com","dir":true,"nodes":[{"key":"/coreos.com/updateengine","dir":true,"nodes":[{"key":"/coreos.com/updateengine/rebootlock","dir":true,"nodes":[{"key":"/coreos.com/updateengine/rebootlock/semaphore","value":"{\"semaphore\":1,\"max\":1,\"holders\":null}","modifiedIndex":6,"createdIndex":6}],"modifiedIndex":6,"createdIndex":6}],"modifiedIndex":6,"createdIndex":6}],"modifiedIndex":6,"createdIndex":6}. . .

Другая полезная информация, доступная за пределами обычного пространства ключей, - это информация о версии, доступная здесь:

curl -L http://127.0.0.1:4001/version

etcd 0.4.6

Вы можете просмотреть статистику о взаимоотношениях каждого лидера кластера с каждым подписчиком, посетив эту конечную точку:

curl -L http://127.0.0.1:4001/v2/stats/leader

{"leader":"921a7241c31a499a97d43f785108b17c","followers":{"27987f5eaac243f88ca6823b47012c5b":{"latency":{"current":1.607038,"average":1.3762888642395448,"standardDeviation":1.4404313533578545,"minimum":0.471432,"maximum":322.728852},"counts":{"fail":0,"success":98718}},"2ddbdb7c872b4bc59dd1969ac166501e":{"latency":{"current":1.584985,"average":1.1554367141497013,"standardDeviation":0.6872303198242179,"minimum":0.427485,"maximum":31.959235},"counts":{"fail":0,"success":98723}}}}

Аналогичная операция может быть использована для определения статистики о машине, на которой вы сейчас находитесь:

curl -L http://127.0.0.1:4001/v2/stats/self

{"name":"921a7241c31a499a97d43f785108b17c","state":"leader","startTime":"2014-09-11T16:42:03.035382298Z","leaderInfo":{"leader":"921a7241c31a499a97d43f785108b17c","uptime":"1h19m11.469872568s","startTime":"2014-09-12T19:47:25.242151859Z"},"recvAppendRequestCnt":1944480,"sendAppendRequestCnt":201817,"sendPkgRate":40.403374523779064,"sendBandwidthRate":3315.096879676072}

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

curl -L http://127.0.0.1:4001/v2/stats/store

{"getsSuccess":78823,"getsFail":14,"setsSuccess":121370,"setsFail":4,"deleteSuccess":28,"deleteFail":32,"updateSuccess":20468,"updateFail":4,"createSuccess":39,"createFail":102340,"compareAndSwapSuccess":51169,"compareAndSwapFail":0,"compareAndDeleteSuccess":0,"compareAndDeleteFail":0,"expireCount":3,"watchers":6}

Это лишь некоторые из операций, которые можно использовать для управления + etcd + через API.

Конфигурация Etcd

Сервис + etcd + может быть настроен несколькими различными способами.

Первый способ - передать параметры с помощью файла + cloud-config +, который вы используете для начальной загрузки ваших узлов. В руководстве по начальной загрузке вы немного узнали о том, как это сделать:

#cloud-config

coreos:
 etcd:
   discovery: https://discovery.etcd.io/
   addr: $private_ipv4:4001
   peer-addr: $private_ipv4:7001
. . .

Чтобы увидеть доступные опции, используйте флаг + -h + с + etcd +:

etcd -h

Чтобы включить эти параметры в ваш + cloud-config +, просто снимите начальную черту и отделите ключи от значений двоеточием вместо знака равенства. Итак, + -peer-addr = <хост: порт> + становится + peer-addr: <хост: порт> +.

После прочтения файла + cloud-config + CoreOS преобразует их в переменные среды в файле-заглушке, который используется для запуска службы.

Другой способ изменить настройки для + etcd + - через API. Обычно это делается с помощью порта + 7001 + вместо стандартного + 4001 +, который используется для ключевых запросов.

Например, вы можете получить некоторые из текущих значений конфигурации, набрав:

curl -L http://127.0.0.1:7001/v2/admin/config

{"activeSize":9,"removeDelay":1800,"syncInterval":5}

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

curl -L http://127.0.0.1:7001/v2/admin/config -XPUT -d '{"activeSize":9,"removeDelay":1800,"syncInterval":5}'

{"activeSize":9,"removeDelay":1800,"syncInterval":5}

Чтобы получить список машин, вы можете перейти к конечной точке + / v2 / admin / machines +:

curl -L http://127.0.0.1:7001/v2/admin/machines

[{"name":"27987f5eaac243f88ca6823b47012c5b","state":"follower","clientURL":"http://10.132.248.121:4001","peerURL":"http://10.132.248.121:7001"},{"name":"2ddbdb7c872b4bc59dd1969ac166501e","state":"follower","clientURL":"http://10.132.252.38:4001","peerURL":"http://10.132.252.38:7001"},{"name":"921a7241c31a499a97d43f785108b17c","state":"leader","clientURL":"http://10.132.248.118:4001","peerURL":"http://10.132.248.118:7001"}]

Это может быть использовано для принудительного удаления машин из кластера с помощью метода DELETE.

Заключение

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

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

TOC