From e196a0e8d29463ddf1096f357e75f542d088a704 Mon Sep 17 00:00:00 2001 From: Hitoshi Mitake Date: Mon, 18 Jan 2016 15:24:59 +0900 Subject: [PATCH] Documentation: add a doc for using the go client library This commit adds a document that provides tips of how to use the go client library. Currently it describes how to use the client.SelectionMode parameter that is added in https://github.com/coreos/etcd/pull/4030. --- Documentation/go_client.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 Documentation/go_client.md diff --git a/Documentation/go_client.md b/Documentation/go_client.md new file mode 100644 index 000000000..11e3ae3db --- /dev/null +++ b/Documentation/go_client.md @@ -0,0 +1,16 @@ +# etcd go client API + +This document describes using the etcd client Go package `github.com/coreos/etcd/client`. + +## Endpoint Selection Mode + +Programs call `client.New()` to create an etcd client instance, passing configuration through the `client.Config` parameter. `client.Config`'s `SelectionMode` member is an `EndpointSelectionMode` `enum` that specifies the policy for choosing the etcd cluster node to which requests are sent. +. + +### EndpointSelectionRandom (default) + +The default value of the `SelectionMode` is `EndpointSelectionRandom`. As the name implies, the client object will pick a node from the members of the cluster in a random fashion. If the cluster has three members, A, B, and C, the client picks any node from its three members as its request destination. + +### EndpointSelectionPrioritizeLeader + +If `SelectionMode` is set to `EndpointSelectionPrioritizeLeader`, requests are sent directly to the cluster leader. This reduces forwarding roundtrips compared to making requests to etcd followers who then forward them to the cluster leader. In the event of a leader failure, however, clients configured this way cannot prioritize among the remaining etcd followers. Therefore, when a client sets `SelectionMode` to `EndpointSelectionPrioritizeLeader`, it must use `client.AutoSync()` to maintain its knowledge of current cluster state.