Skip to content

Commit

Permalink
docs: update links to "go.etcd.io"
Browse files Browse the repository at this point in the history
Signed-off-by: Gyuho Lee <[email protected]>
  • Loading branch information
gyuho committed Aug 29, 2018
1 parent 02b94fc commit e52b861
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 18 deletions.
8 changes: 4 additions & 4 deletions docs/client-architecture.rst
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,9 @@ Client Requirements

*Correctness*. Requests may fail in the presence of server faults. However, it never violates consistency guarantees: global ordering properties, never write corrupted data, at-most once semantics for mutable operations, watch never observes partial events, and so on.

*Liveness*. Servers may fail or disconnect briefly. Clients should make progress in either way. Clients should `never deadlock <https://github.com/coreos/etcd/issues/8980>`_ waiting for a server to come back from offline, unless configured to do so. Ideally, clients detect unavailable servers with HTTP/2 ping and failover to other nodes with clear error messages.
*Liveness*. Servers may fail or disconnect briefly. Clients should make progress in either way. Clients should `never deadlock <https://github.com/etcd-io/etcd/issues/8980>`_ waiting for a server to come back from offline, unless configured to do so. Ideally, clients detect unavailable servers with HTTP/2 ping and failover to other nodes with clear error messages.

*Effectiveness*. Clients should operate effectively with minimum resources: previous TCP connections should be `gracefully closed <https://github.com/coreos/etcd/issues/9212>`_ after endpoint switch. Failover mechanism should effectively predict the next replica to connect, without wastefully retrying on failed nodes.
*Effectiveness*. Clients should operate effectively with minimum resources: previous TCP connections should be `gracefully closed <https://github.com/etcd-io/etcd/issues/9212>`_ after endpoint switch. Failover mechanism should effectively predict the next replica to connect, without wastefully retrying on failed nodes.

*Portability*. Official client should be clearly documented and its implementation be applicable to other language bindings. Error handling between different language bindings should be consistent. Since etcd is fully committed to gRPC, implementation should be closely aligned with gRPC long-term design goals (e.g. pluggable retry policy should be compatible with `gRPC retry <https://github.com/grpc/proposal/blob/master/A6-client-retries.md>`_). Upgrades between two client versions should be non-disruptive.

Expand Down Expand Up @@ -110,7 +110,7 @@ Stream RPCs, such as Watch and KeepAlive, are often requested with no timeouts.
clientv3-grpc1.7: Balancer Limitation
-------------------------------------

``clientv3-grpc1.7`` balancer sends HTTP/2 keepalives to detect disconnects from streaming requests. It is a simple gRPC server ping mechanism and does not reason about cluster membership, thus unable to detect network partitions. Since partitioned gRPC server can still respond to client pings, balancer may get stuck with a partitioned node. Ideally, keepalive ping detects partition and triggers endpoint switch, before request time-out (see `issue#8673 <https://github.com/coreos/etcd/issues/8673>`_ and *Figure 7*).
``clientv3-grpc1.7`` balancer sends HTTP/2 keepalives to detect disconnects from streaming requests. It is a simple gRPC server ping mechanism and does not reason about cluster membership, thus unable to detect network partitions. Since partitioned gRPC server can still respond to client pings, balancer may get stuck with a partitioned node. Ideally, keepalive ping detects partition and triggers endpoint switch, before request time-out (see `issue#8673 <https://github.com/etcd-io/etcd/issues/8673>`_ and *Figure 7*).

.. image:: img/client-architecture-balancer-figure-07.png
:align: center
Expand Down Expand Up @@ -146,6 +146,6 @@ clientv3-grpc1.14: Balancer Limitation

Improvements can be made by caching the status of each endpoint. For instance, balancer can ping each server in advance to maintain a list of healthy candidates, and use this information when doing round-robin. Or when disconnected, balancer can prioritize healthy endpoints. This may complicate the balancer implementation, thus can be addressed in later versions.

Client-side keepalive ping still does not reason about network partitions. Streaming request may get stuck with a partitioned node. Advanced health checking service need to be implemented to understand the cluster membership (see `issue#8673 <https://github.com/coreos/etcd/issues/8673>`_ for more detail).
Client-side keepalive ping still does not reason about network partitions. Streaming request may get stuck with a partitioned node. Advanced health checking service need to be implemented to understand the cluster membership (see `issue#8673 <https://github.com/etcd-io/etcd/issues/8673>`_ for more detail).

Currently, retry logic is handled manually as an interceptor. This may be simplified via `official gRPC retries <https://github.com/grpc/proposal/blob/master/A6-client-retries.md>`_.
28 changes: 14 additions & 14 deletions docs/client-feature-matrix.rst
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Features
+----------------------------------------+-------------------------+-------------------+


`KV <https://godoc.org/github.com/coreos/etcd/clientv3#KV>`_
`KV <https://godoc.org/go.etcd.io/etcd/clientv3#KV>`_
============================================================

+---------------+-------------------------+-------------------+
Expand All @@ -59,7 +59,7 @@ Features
+---------------+-------------------------+-------------------+


`Lease <https://godoc.org/github.com/coreos/etcd/clientv3#Lease>`_
`Lease <https://godoc.org/go.etcd.io/etcd/clientv3#Lease>`_
==================================================================

+-------------------+-------------------------+-------------------+
Expand All @@ -79,7 +79,7 @@ Features
+-------------------+-------------------------+-------------------+


`Watcher <https://godoc.org/github.com/coreos/etcd/clientv3#Watcher>`_
`Watcher <https://godoc.org/go.etcd.io/etcd/clientv3#Watcher>`_
======================================================================

+---------------------+-------------------------+-------------------+
Expand All @@ -91,7 +91,7 @@ Features
+---------------------+-------------------------+-------------------+


`Cluster <https://godoc.org/github.com/coreos/etcd/clientv3#Cluster>`_
`Cluster <https://godoc.org/go.etcd.io/etcd/clientv3#Cluster>`_
======================================================================

+------------------+-------------------------+-------------------+
Expand All @@ -107,7 +107,7 @@ Features
+------------------+-------------------------+-------------------+


`Maintenance <https://godoc.org/github.com/coreos/etcd/clientv3#Maintenance>`_
`Maintenance <https://godoc.org/go.etcd.io/etcd/clientv3#Maintenance>`_
==============================================================================

+-----------------+-------------------------+-------------------+
Expand All @@ -129,7 +129,7 @@ Features
+-----------------+-------------------------+-------------------+


`Auth <https://godoc.org/github.com/coreos/etcd/clientv3#Auth>`_
`Auth <https://godoc.org/go.etcd.io/etcd/clientv3#Auth>`_
================================================================

+----------------------------+-------------------------+-------------------+
Expand Down Expand Up @@ -167,7 +167,7 @@ Features
+----------------------------+-------------------------+-------------------+


`clientv3util <https://godoc.org/github.com/coreos/etcd/clientv3/clientv3util>`_
`clientv3util <https://godoc.org/go.etcd.io/etcd/clientv3/clientv3util>`_
================================================================================

+---------------------------+-------------------------+-------------------+
Expand All @@ -179,7 +179,7 @@ Features
+---------------------------+-------------------------+-------------------+


`concurrency <https://godoc.org/github.com/coreos/etcd/clientv3/concurrency>`_
`concurrency <https://godoc.org/go.etcd.io/etcd/clientv3/concurrency>`_
==============================================================================

+----------------------------------------+-------------------------+-------------------+
Expand Down Expand Up @@ -211,7 +211,7 @@ Features
+----------------------------------------+-------------------------+-------------------+


`leasing <https://godoc.org/github.com/coreos/etcd/clientv3/leasing>`_
`leasing <https://godoc.org/go.etcd.io/etcd/clientv3/leasing>`_
======================================================================

+---------------------------+-------------------------+-------------------+
Expand All @@ -221,7 +221,7 @@ Features
+---------------------------+-------------------------+-------------------+


`mirror <https://godoc.org/github.com/coreos/etcd/clientv3/mirror>`_
`mirror <https://godoc.org/go.etcd.io/etcd/clientv3/mirror>`_
======================================================================

+------------------+-------------------------+-------------------+
Expand All @@ -233,7 +233,7 @@ Features
+------------------+-------------------------+-------------------+


`namespace <https://godoc.org/github.com/coreos/etcd/clientv3/namespace>`_
`namespace <https://godoc.org/go.etcd.io/etcd/clientv3/namespace>`_
==========================================================================

+-------------+-------------------------+-------------------+
Expand All @@ -247,7 +247,7 @@ Features
+-------------+-------------------------+-------------------+


`naming <https://godoc.org/github.com/coreos/etcd/clientv3/naming>`_
`naming <https://godoc.org/go.etcd.io/etcd/clientv3/naming>`_
====================================================================

+--------------------+-------------------------+-------------------+
Expand All @@ -257,7 +257,7 @@ Features
+--------------------+-------------------------+-------------------+


`ordering <https://godoc.org/github.com/coreos/etcd/clientv3/ordering>`_
`ordering <https://godoc.org/go.etcd.io/etcd/clientv3/ordering>`_
========================================================================

+----------+-------------------------+-------------------+
Expand All @@ -267,7 +267,7 @@ Features
+----------+-------------------------+-------------------+


`snapshot <https://godoc.org/github.com/coreos/etcd/clientv3/snapshot>`_
`snapshot <https://godoc.org/go.etcd.io/etcd/clientv3/snapshot>`_
========================================================================

+-------------+-------------------------+-------------------+
Expand Down

0 comments on commit e52b861

Please sign in to comment.