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

     1  ---
     2  title: etcd gateway
     3  ---
     4  
     5  ## What is etcd gateway
     6  
     7  etcd gateway is a simple TCP proxy that forwards network data to the etcd cluster. The gateway is stateless and transparent; it neither inspects client requests nor interferes with cluster responses. It does not terminate TLS connections, do TLS handshakes on behalf of its clients, or verify if the connection is secured.
     8  
     9  The gateway supports multiple etcd server endpoints and works on a simple round-robin policy. It only routes to available endpoints and hides failures from its clients. Other retry policies, such as weighted round-robin, may be supported in the future.
    10  
    11  ## When to use etcd gateway
    12  
    13  Every application that accesses etcd must first have the address of an etcd cluster client endpoint. If multiple applications on the same server access the same etcd cluster, every application still needs to know the advertised client endpoints of the etcd cluster. If the etcd cluster is reconfigured to have different endpoints, every application may also need to update its endpoint list. This wide-scale reconfiguration is both tedious and error prone.
    14  
    15  etcd gateway solves this problem by serving as a stable local endpoint. A typical etcd gateway configuration has each machine running a gateway listening on a local address and every etcd application connecting to its local gateway. The upshot is only the gateway needs to update its endpoints instead of updating each and every application.
    16  
    17  In summary, to automatically propagate cluster endpoint changes, the etcd gateway runs on every machine serving multiple applications accessing the same etcd cluster.
    18  
    19  ## When not to use etcd gateway
    20  
    21  - Improving performance
    22  
    23  The gateway is not designed for improving etcd cluster performance. It does not provide caching, watch coalescing or batching. The etcd team is developing a caching proxy designed for improving cluster scalability. 
    24  
    25  - Running on a cluster management system
    26  
    27  Advanced cluster management systems like Kubernetes natively support service discovery. Applications can access an etcd cluster with a DNS name or a virtual IP address managed by the system. For example, kube-proxy is equivalent to etcd gateway.
    28  
    29  ## Start etcd gateway
    30  
    31  Consider an etcd cluster with the following static endpoints:
    32  
    33  |Name|Address|Hostname|
    34  |------|---------|------------------|
    35  |infra0|10.0.1.10|infra0.example.com|
    36  |infra1|10.0.1.11|infra1.example.com|
    37  |infra2|10.0.1.12|infra2.example.com|
    38  
    39  Start the etcd gateway to use these static endpoints with the command:
    40  
    41  ```bash
    42  $ etcd gateway start --endpoints=infra0.example.com,infra1.example.com,infra2.example.com
    43  2016-08-16 11:21:18.867350 I | tcpproxy: ready to proxy client requests to [...]
    44  ```
    45  
    46  Alternatively, if using DNS for service discovery, consider the DNS SRV entries:
    47  
    48  ```bash
    49  $ dig +noall +answer SRV _etcd-client._tcp.example.com
    50  _etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra0.example.com.
    51  _etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra1.example.com.
    52  _etcd-client._tcp.example.com. 300 IN SRV 0 0 2379 infra2.example.com.
    53  ```
    54  
    55  ```bash
    56  $ dig +noall +answer infra0.example.com infra1.example.com infra2.example.com
    57  infra0.example.com.  300  IN  A  10.0.1.10
    58  infra1.example.com.  300  IN  A  10.0.1.11
    59  infra2.example.com.  300  IN  A  10.0.1.12
    60  ```
    61  
    62  Start the etcd gateway to fetch the endpoints from the DNS SRV entries with the command:
    63  
    64  ```bash
    65  $ etcd gateway start --discovery-srv=example.com
    66  2016-08-16 11:21:18.867350 I | tcpproxy: ready to proxy client requests to [...]
    67  ```
    68  
    69  ## Configuration flags
    70  
    71  ### etcd cluster
    72  
    73  #### --endpoints
    74  
    75   * Comma-separated list of etcd server targets for forwarding client connections.
    76   * Default: `127.0.0.1:2379`
    77   * Invalid example: `https://127.0.0.1:2379` (gateway does not terminate TLS). Note that the gateway does not verify the HTTP schema or inspect the requests, it only forwards requests to the given endpoints.
    78  
    79  #### --discovery-srv
    80  
    81   * DNS domain used to bootstrap cluster endpoints through SRV recrods.
    82   * Default: (not set)
    83  
    84  ### Network
    85  
    86  #### --listen-addr
    87  
    88   * Interface and port to bind for accepting client requests.
    89   * Default: `127.0.0.1:23790`
    90  
    91  #### --retry-delay
    92  
    93   * Duration of delay before retrying to connect to failed endpoints.
    94   * Default: 1m0s
    95   * Invalid example: "123" (expects time unit in format)
    96  
    97  ### Security
    98  
    99  #### --insecure-discovery
   100  
   101   * Accept SRV records that are insecure or susceptible to man-in-the-middle attacks.
   102   * Default: `false`
   103  
   104  #### --trusted-ca-file
   105  
   106   * Path to the client TLS CA file for the etcd cluster to verify the endpoints returned from SRV discovery. Note that it is ONLY used for authenticating the discovered endpoints rather than creating connections for data transferring. The gateway never terminates TLS connections or create TLS connections on behalf of its clients.
   107   * Default: (not set)