go.etcd.io/etcd@v3.3.27+incompatible/client/README.md (about)

     1  # etcd/client
     2  
     3  etcd/client is the Go client library for etcd.
     4  
     5  [![GoDoc](https://godoc.org/github.com/coreos/etcd/client?status.png)](https://godoc.org/github.com/coreos/etcd/client)
     6  
     7  etcd uses `cmd/vendor` directory to store external dependencies, which are
     8  to be compiled into etcd release binaries. `client` can be imported without
     9  vendoring. For full compatibility, it is recommended to vendor builds using
    10  etcd's vendored packages, using tools like godep, as in
    11  [vendor directories](https://golang.org/cmd/go/#hdr-Vendor_Directories).
    12  For more detail, please read [Go vendor design](https://golang.org/s/go15vendor).
    13  
    14  ## Install
    15  
    16  ```bash
    17  go get github.com/coreos/etcd/client
    18  ```
    19  
    20  ## Usage
    21  
    22  ```go
    23  package main
    24  
    25  import (
    26  	"log"
    27  	"time"
    28  	"context"
    29  
    30  	"github.com/coreos/etcd/client"
    31  )
    32  
    33  func main() {
    34  	cfg := client.Config{
    35  		Endpoints:               []string{"http://127.0.0.1:2379"},
    36  		Transport:               client.DefaultTransport,
    37  		// set timeout per request to fail fast when the target endpoint is unavailable
    38  		HeaderTimeoutPerRequest: time.Second,
    39  	}
    40  	c, err := client.New(cfg)
    41  	if err != nil {
    42  		log.Fatal(err)
    43  	}
    44  	kapi := client.NewKeysAPI(c)
    45  	// set "/foo" key with "bar" value
    46  	log.Print("Setting '/foo' key with 'bar' value")
    47  	resp, err := kapi.Set(context.Background(), "/foo", "bar", nil)
    48  	if err != nil {
    49  		log.Fatal(err)
    50  	} else {
    51  		// print common key info
    52  		log.Printf("Set is done. Metadata is %q\n", resp)
    53  	}
    54  	// get "/foo" key's value
    55  	log.Print("Getting '/foo' key value")
    56  	resp, err = kapi.Get(context.Background(), "/foo", nil)
    57  	if err != nil {
    58  		log.Fatal(err)
    59  	} else {
    60  		// print common key info
    61  		log.Printf("Get is done. Metadata is %q\n", resp)
    62  		// print value
    63  		log.Printf("%q key has %q value\n", resp.Node.Key, resp.Node.Value)
    64  	}
    65  }
    66  ```
    67  
    68  ## Error Handling
    69  
    70  etcd client might return three types of errors.
    71  
    72  - context error
    73  
    74  Each API call has its first parameter as `context`. A context can be canceled or have an attached deadline. If the context is canceled or reaches its deadline, the responding context error will be returned no matter what internal errors the API call has already encountered.
    75  
    76  - cluster error
    77  
    78  Each API call tries to send request to the cluster endpoints one by one until it successfully gets a response. If a requests to an endpoint fails, due to exceeding per request timeout or connection issues, the error will be added into a list of errors. If all possible endpoints fail, a cluster error that includes all encountered errors will be returned.
    79  
    80  - response error
    81  
    82  If the response gets from the cluster is invalid, a plain string error will be returned. For example, it might be a invalid JSON error.
    83  
    84  Here is the example code to handle client errors:
    85  
    86  ```go
    87  cfg := client.Config{Endpoints: []string{"http://etcd1:2379","http://etcd2:2379","http://etcd3:2379"}}
    88  c, err := client.New(cfg)
    89  if err != nil {
    90  	log.Fatal(err)
    91  }
    92  
    93  kapi := client.NewKeysAPI(c)
    94  resp, err := kapi.Set(ctx, "test", "bar", nil)
    95  if err != nil {
    96  	if err == context.Canceled {
    97  		// ctx is canceled by another routine
    98  	} else if err == context.DeadlineExceeded {
    99  		// ctx is attached with a deadline and it exceeded
   100  	} else if cerr, ok := err.(*client.ClusterError); ok {
   101  		// process (cerr.Errors)
   102  	} else {
   103  		// bad cluster endpoints, which are not etcd servers
   104  	}
   105  }
   106  ```
   107  
   108  
   109  ## Caveat
   110  
   111  1. etcd/client prefers to use the same endpoint as long as the endpoint continues to work well. This saves socket resources, and improves efficiency for both client and server side. This preference doesn't remove consistency from the data consumed by the client because data replicated to each etcd member has already passed through the consensus process.
   112  
   113  2. etcd/client does round-robin rotation on other available endpoints if the preferred endpoint isn't functioning properly. For example, if the member that etcd/client connects to is hard killed, etcd/client will fail on the first attempt with the killed member, and succeed on the second attempt with another member. If it fails to talk to all available endpoints, it will return all errors happened.
   114  
   115  3. Default etcd/client cannot handle the case that the remote server is SIGSTOPed now. TCP keepalive mechanism doesn't help in this scenario because operating system may still send TCP keep-alive packets. Over time we'd like to improve this functionality, but solving this issue isn't high priority because a real-life case in which a server is stopped, but the connection is kept alive, hasn't been brought to our attention.
   116  
   117  4. etcd/client cannot detect whether a member is healthy with watches and non-quorum read requests. If the member is isolated from the cluster, etcd/client may retrieve outdated data. Instead, users can either issue quorum read requests or monitor the /health endpoint for member health information.