go.etcd.io/etcd@v3.3.27+incompatible/Documentation/dev-guide/api_grpc_gateway.md (about)

     1  ---
     2  title: Why gRPC gateway
     3  ---
     4  
     5  etcd v3 uses [gRPC][grpc] for its messaging protocol. The etcd project includes a gRPC-based [Go client][go-client] and a command line utility, [etcdctl][etcdctl], for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON [gRPC gateway][grpc-gateway]. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.
     6  
     7  ## Using gRPC gateway
     8  
     9  The gateway accepts a [JSON mapping][json-mapping] for etcd's [protocol buffer][api-ref] message definitions. Note that `key` and `value` fields are defined as byte arrays and therefore must be base64 encoded in JSON. The following examples use `curl`, but any HTTP/JSON client should work all the same.
    10  
    11  ### Notes
    12  
    13  gRPC gateway endpoint has changed since etcd v3.3:
    14  
    15  - etcd v3.2 or before uses only `[CLIENT-URL]/v3alpha/*`.
    16  - etcd v3.3 uses `[CLIENT-URL]/v3beta/*` while keeping `[CLIENT-URL]/v3alpha/*`.
    17  - etcd v3.4 uses `[CLIENT-URL]/v3/*` while keeping `[CLIENT-URL]/v3beta/*`.
    18    - **`[CLIENT-URL]/v3alpha/*` is deprecated**.
    19  - etcd v3.5 or later uses only `[CLIENT-URL]/v3/*`.
    20    - **`[CLIENT-URL]/v3beta/*` is deprecated**.
    21  
    22  gRPC-gateway does not support authentication using TLS Common Name.
    23  
    24  ### Put and get keys
    25  
    26  Use the `/v3/kv/range` and `/v3/kv/put` services to read and write keys:
    27  
    28  ```bash
    29  <<COMMENT
    30  https://www.base64encode.org/
    31  foo is 'Zm9v' in Base64
    32  bar is 'YmFy'
    33  COMMENT
    34  
    35  curl -L http://localhost:2379/v3/kv/put \
    36    -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
    37  # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"}}
    38  
    39  curl -L http://localhost:2379/v3/kv/range \
    40    -X POST -d '{"key": "Zm9v"}'
    41  # {"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"}
    42  
    43  # get all keys prefixed with "foo"
    44  curl -L http://localhost:2379/v3/kv/range \
    45    -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}'
    46  # {"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"}
    47  ```
    48  
    49  ### Watch keys
    50  
    51  Use the `/v3/watch` service to watch keys:
    52  
    53  ```bash
    54  curl -N http://localhost:2379/v3/watch \
    55    -X POST -d '{"create_request": {"key":"Zm9v"} }' &
    56  # {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"1","raft_term":"2"},"created":true}}
    57  
    58  curl -L http://localhost:2379/v3/kv/put \
    59    -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1
    60  # {"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"}}]}}
    61  ```
    62  
    63  ### Transactions
    64  
    65  Issue a transaction with `/v3/kv/txn`:
    66  
    67  ```bash
    68  # target CREATE
    69  curl -L http://localhost:2379/v3/kv/txn \
    70    -X POST \
    71    -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}'
    72  # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"3","raft_term":"2"},"succeeded":true,"responses":[{"response_put":{"header":{"revision":"3"}}}]}
    73  ```
    74  
    75  ```bash
    76  # target VERSION
    77  curl -L http://localhost:2379/v3/kv/txn \
    78    -X POST \
    79    -d '{"compare":[{"version":"4","result":"EQUAL","target":"VERSION","key":"Zm9v"}],"success":[{"requestRange":{"key":"Zm9v"}}]}'
    80  # {"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"}}]}
    81  ```
    82  
    83  ### Authentication
    84  
    85  Set up authentication with the `/v3/auth` service:
    86  
    87  ```bash
    88  # create root user
    89  curl -L http://localhost:2379/v3/auth/user/add \
    90    -X POST -d '{"name": "root", "password": "pass"}'
    91  # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
    92  
    93  # create root role
    94  curl -L http://localhost:2379/v3/auth/role/add \
    95    -X POST -d '{"name": "root"}'
    96  # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
    97  
    98  # grant root role
    99  curl -L http://localhost:2379/v3/auth/user/grant \
   100    -X POST -d '{"user": "root", "role": "root"}'
   101  # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
   102  
   103  # enable auth
   104  curl -L http://localhost:2379/v3/auth/enable -X POST -d '{}'
   105  # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
   106  ```
   107  
   108  Authenticate with etcd for an authentication token using `/v3/auth/authenticate`:
   109  
   110  ```bash
   111  # get the auth token for the root user
   112  curl -L http://localhost:2379/v3/auth/authenticate \
   113    -X POST -d '{"name": "root", "password": "pass"}'
   114  # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"},"token":"sssvIpwfnLAcWAQH.9"}
   115  ```
   116  
   117  Set the `Authorization` header to the authentication token to fetch a key using authentication credentials:
   118  
   119  ```bash
   120  curl -L http://localhost:2379/v3/kv/put \
   121    -H 'Authorization : sssvIpwfnLAcWAQH.9' \
   122    -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
   123  # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"2","raft_term":"2"}}
   124  ```
   125  
   126  ## Swagger
   127  
   128  Generated [Swagger][swagger] API definitions can be found at [rpc.swagger.json][swagger-doc].
   129  
   130  [api-ref]: ./api_reference_v3.md
   131  [go-client]: https://github.com/coreos/etcd/tree/master/clientv3
   132  [etcdctl]: https://github.com/coreos/etcd/tree/master/etcdctl
   133  [grpc]: https://www.grpc.io/
   134  [grpc-gateway]: https://github.com/grpc-ecosystem/grpc-gateway
   135  [json-mapping]: https://developers.google.com/protocol-buffers/docs/proto3#json
   136  [swagger]: http://swagger.io/
   137  [swagger-doc]: apispec/swagger/rpc.swagger.json