Чому 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"}}
Swagger
Згенеровані Swagger визначення API можна знайти за посиланням rpc.swagger.json.
Відгук
Чи це було корисним?
Раді чути! Будь ласка, повідомте нам, як ми можемо зробити краще.
Дуже шкода це чути. Будь ласка, повідомте нам, як ми можемо зробити краще.