Чому gRPC gateway
etcd v3 використовує gRPC для свого протоколу обміну повідомленнями. Проєкт etcd включає клієнт на основі gRPC Go client та утиліту командного рядка etcdctl для спілкування з кластером etcd через gRPC. Для мов, які не підтримують gRPC, etcd надає JSON gRPC gateway. Цей шлюз обслуговує RESTful проксі, який перетворює HTTP/JSON запити в gRPC повідомлення.
Використання gRPC gateway
Шлюз приймає JSON mapping для protocol buffer визначень повідомлень etcd. Зверніть увагу, що поля key та value визначені як масиви байтів і тому повинні бути закодовані в base64 у JSON. Наступні приклади використовують curl, але будь-який HTTP/JSON клієнт повинен працювати так само.
Примітки
Точка доступу gRPC gateway змінилася з версії 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 не підтримує автентифікацію за допомогою TLS Common Name.
Додавання та отримання ключів
Використовуйте сервіси /v3/kv/range та /v3/kv/put для читання та запису ключів:
<<COMMENT
https://www.base64encode.org/
foo це 'Zm9v' у Base64
bar це '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"}
# отримати всі ключі з префіксом "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:
# ціль 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"}}}]}
# ціль 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:
# створити користувача root
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"}}
# створити роль root
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"}}
# надати роль root
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:
# отримати токен автентифікації для користувача root
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 gateway перетворює статус 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
Згенеровані Swagger визначення API можна знайти за посиланням rpc.swagger.json.
Зворотний зв’язок
Чи була ця сторінка корисною?
Раді чути! Будь ласка, повідомте нам, як ми можемо зробити краще.
Дуже шкода це чути. Будь ласка, повідомте нам, як ми можемо зробити краще.