Взаємодія з etcd

Користувачі здебільшого взаємодіють з etcd, встановлюючи або отримуючи значення ключа. У цьому розділі описано, як це зробити за допомогою etcdctl, інструменту командного рядка для взаємодії з сервером etcd. Описані концепції повинні застосовуватися до gRPC API або API бібліотеки клієнта.

Версія API, яку використовує etcdctl для взаємодії з etcd, може бути встановлена на версію 2 або 3 за допомогою змінної середовища ETCDCTL_API. Стандартно, etcdctl на master (3.4) використовує API v3, а попередні версії (3.3 і раніше) стандартно використовують API v2.

Зверніть увагу, що будь-який ключ, створений за допомогою API v2, не зможе бути запитаний через API v3. Запит etcdctl get API v3 для ключа v2 завершиться з кодом 0 і без даних ключа, це очікувана поведінка.

export ETCDCTL_API=3

Знайти версії

Версії etcdctl та Server API можуть бути корисними для знаходження відповідних команд для виконання різних операцій на etcd.

Ось команда для знаходження версій:

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

Записати ключ

Застосунки зберігають ключі в кластері etcd, записуючи їх. Кожен збережений ключ реплікується до всіх членів кластера etcd через протокол Raft для досягнення узгодженості та надійності.

Ось команда для встановлення значення bar для ключа foo:

$ etcdctl put foo bar
OK

Також ключ може бути встановлений на певний інтервал часу, прикріпивши до нього оренду.

Ось команда для встановлення значення ключа foo1 на bar1 на 10 секунд:

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

Примітка: Ідентифікатор оренди 1234abcd у наведеній вище команді належить до ідентифікатора, повернутого при створенні оренди на 10 секунд. Цей ідентифікатор потім може бути прикріплений до ключа.

Читання ключів

Застосунки можуть читати значення ключів з кластера etcd. Запити можуть читати один ключ або діапазон ключів.

Припустимо, кластер etcd зберіг наступні ключі:

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

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

$ etcdctl get foo
foo
bar

Ось команда для читання значення ключа foo у шістнадцятковому форматі:

$ etcdctl get foo --hex
\x66\x6f\x6f          # Ключ
\x62\x61\x72          # Значення

Ось команда для читання лише значення ключа foo:

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

Ось команда для діапазону ключів від foo до foo3:

$ etcdctl get foo foo3
foo
bar
foo1
bar1
foo2
bar2

Зверніть увагу, що foo3 виключено, оскільки діапазон охоплює напіввідкритий інтервал [foo, foo3), виключаючи foo3.

Ось команда для діапазону всіх ключів з префіксом 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

Читання попередніх версій ключів

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

Припустимо, кластер etcd вже має наступні ключі:

foo = bar         # ревізія = 2
foo1 = bar1       # ревізія = 3
foo = bar_new     # ревізія = 4
foo1 = bar1_new   # ревізія = 5

Ось приклад доступу до попередніх версій ключів:

$ etcdctl get --prefix foo # доступ до найновіших версій ключів
foo
bar_new
foo1
bar1_new

$ etcdctl get --prefix --rev=4 foo # доступ до версій ключів в ревізії 4
foo
bar_new
foo1
bar1

$ etcdctl get --prefix --rev=3 foo # доступ до версій ключів в ревізії 3
foo
bar
foo1
bar1

$ etcdctl get --prefix --rev=2 foo # доступ до версій ключів в ревізії 2
foo
bar

$ etcdctl get --prefix --rev=1 foo # доступ до версій ключів в ревізії 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 # один ключ видалено

Ось команда для видалення ключів у діапазоні від foo до foo9:

$ etcdctl del foo foo9
2 # два ключі видалено

Ось команда для видалення ключа zoo з виводом видаленого ключа та значення:

$ etcdctl del --prev-kv zoo
1   # один ключ видалено
zoo # видалений ключ
val # значення видаленого ключа

Ось команда для видалення ключів з префіксом zoo:

$ etcdctl del --prefix zoo
2 # два ключі видалено

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

$ etcdctl del --from-key b
2 # два ключі видалено

Спостереження за змінами ключів

Застосунки можуть спостерігати за ключем або діапазоном ключів, щоб відстежувати будь-які оновлення.

Ось команда для спостереження за ключем foo:

$ etcdctl watch foo
# в іншому терміналі: etcdctl put foo bar
PUT
foo
bar

Ось команда для спостереження за ключем foo у шістнадцятковому форматі:

$ etcdctl watch foo --hex
# в іншому терміналі: etcdctl put foo bar
PUT
\x66\x6f\x6f          # Ключ
\x62\x61\x72          # Значення

Ось команда для спостереження за діапазоном ключів від foo до foo9:

$ etcdctl watch foo foo9
# в іншому терміналі: etcdctl put foo bar
PUT
foo
bar
# в іншому терміналі: etcdctl put foo1 bar1
PUT
foo1
bar1

Ось команда для спостереження за ключами з префіксом foo:

$ etcdctl watch --prefix foo
# в іншому терміналі: etcdctl put foo bar
PUT
foo
bar
# в іншому терміналі: etcdctl put fooz1 barz1
PUT
fooz1
barz1

Ось команда для спостереження за кількома ключами foo та zoo:

$ etcdctl watch -i
$ watch foo
$ watch zoo
# в іншому терміналі: etcdctl put foo bar
PUT
foo
bar
# в іншому терміналі: etcdctl put zoo val
PUT
zoo
val

Спостереження за історичними змінами ключів

Застосунки можуть захотіти спостерігати за історичними змінами ключів у etcd. Наприклад, застосунок може захотіти отримувати всі модифікації ключа; якщо застосунок залишається підключеним до etcd, то watch достатньо. Однак, якщо застосунок або etcd виходить з ладу, зміна може статися під час збою, і застосунок не отримає оновлення в реальному часі. Щоб гарантувати доставлення оновлення, застосунок повинен мати можливість спостерігати за історичними змінами ключів. Для цього застосунок може вказати історичну ревізію на спостереженні, так само як і при читанні попередніх версій ключів.

Припустимо, ми завершили наступну послідовність операцій:

$ etcdctl put foo bar         # ревізія = 2
OK
$ etcdctl put foo1 bar1       # ревізія = 3
OK
$ etcdctl put foo bar_new     # ревізія = 4
OK
$ etcdctl put foo1 bar1_new   # ревізія = 5
OK

Ось приклад спостереження за історичними змінами:

# спостереження за змінами ключа `foo` з ревізії 2
$ etcdctl watch --rev=2 foo
PUT
foo
bar
PUT
foo
bar_new

# спостереження за змінами ключа `foo` з ревізії 3
$ etcdctl watch --rev=3 foo
PUT
foo
bar_new

Ось приклад спостереження лише з останньої історичної зміни:

# спостереження за змінами ключа `foo` та повернення останнього значення ревізії разом із зміненим значенням
$ etcdctl watch --prev-kv foo
# в іншому терміналі: etcdctl put foo bar_latest
PUT
foo         # ключ
bar_new     # останнє значення ключа foo перед зміною
foo         # ключ
bar_latest  # значення ключа foo після зміни

Спостереження за прогресом

Застосунки можуть захотіти перевірити прогрес спостереження, щоб визначити, наскільки актуальний потік спостереження. Наприклад, якщо спостереження використовується для оновлення кешу, може бути корисно знати, чи є кеш застарілим порівняно з ревізією з кворумного читання.

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

$ etcdctl watch -i
$ watch a
$ progress
progress notify: 1
# в іншому терміналі: etcdctl put x 0
# в іншому терміналі: etcdctl put y 1
$ progress
progress notify: 3

Примітка: Номер ревізії у відповіді на повідомлення про прогрес є ревізією з локального вузла сервера etcd, до якого підключений потік спостереження. Якщо цей вузол розділений і не є частиною кворуму, ця ревізія прогресу може бути нижчою, ніж ревізія, повернута кворумним читанням з нерозділеного вузла сервера etcd.

Ущільнені ревізії

Як ми вже згадували, etcd зберігає ревізії, щоб застосунки могли читати попередні версії ключів. Однак, щоб уникнути накопичення необмеженої кількості історії, важливо ущільнювати попередні ревізії. Після ущільнення etcd видаляє історичні ревізії, звільняючи ресурси для майбутнього використання. Всі застарілі дані з ревізіями до ущільненої ревізії будуть недоступні.

Ось команда для ущільнення ревізій:

$ etcdctl compact 5
compacted revision 5

# будь-які ревізії до ущільненої недоступні
$ etcdctl get --rev=4 foo
Error:  rpc error: code = 11 desc = etcdserver: mvcc: required revision has been compacted

Примітка: Поточну ревізію сервера etcd можна знайти за допомогою команди get на будь-якому ключі (наявному або відсутньому) у форматі json. Приклад показано нижче для mykey, який не існує на сервері etcd:

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

Надання оренд

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

Ось команда для надання оренди:

# надання оренди з TTL 60 секунд
$ etcdctl lease grant 60
lease 32695410dcc0ca06 granted with TTL(60s)

# прикріплення ключа foo до оренди 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
# порожня відповідь, оскільки foo видалено через відкликання оренди

Підтримка оренд

Застосунки можуть підтримувати оренду, оновлюючи її 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)
...

Отримання інформації про оренду

Застосунки можуть захотіти знати інформацію про оренду, щоб її можна було оновити або перевірити, чи оренда все ще існує або закінчилася. Застосунки також можуть захотіти знати ключі, до яких прикріплена певна оренда.

Припустимо, ми завершили наступну послідовність операцій:

# надання оренди з TTL 500 секунд
$ etcdctl lease grant 500
lease 694d5765fc71500b granted with TTL(500s)

# прикріплення ключа zoo1 до оренди 694d5765fc71500b
$ etcdctl put zoo1 val1 --lease=694d5765fc71500b
OK

# прикріплення ключа zoo2 до оренди 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])

# якщо оренда закінчилася або не існує, буде надано таку відповідь:
Error:  etcdserver: requested lease not found