[apisix] branch master updated: doc: etcd grpc gateway faq (#2940)

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git


The following commit(s) were added to refs/heads/master by this push:
     new 9e3c34a  doc: etcd grpc gateway faq (#2940)
9e3c34a is described below

commit 9e3c34a0103b88d340285017e34021cbc1f0fde8
Author: Alex Zhang <zc...@gmail.com>
AuthorDate: Thu Dec 3 12:31:57 2020 +0800

    doc: etcd grpc gateway faq (#2940)
---
 FAQ.md    | 26 ++++++++++++++++++++++++++
 FAQ_CN.md | 26 ++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/FAQ.md b/FAQ.md
index 98199b4..a5eb53a 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -299,3 +299,29 @@ If you want to specify a meaningful id to bind APISIX instance to your internal
     apisix:
       id: "your-meaningful-id"
     ```
+
+## Why there are a lot of "failed to fetch data from etcd, failed to read etcd dir, etcd key: xxxxxx" errors in error.log?
+
+First please make sure the network between APISIX and etcd cluster is not partitioned.
+
+If the network is healthy, please check whether your etcd cluster enables the [gRPC gateway](https://etcd.io/docs/v3.4.0/dev-guide/api_grpc_gateway/).  However, The default case for this feature is different when use command line options or configuration file to start etcd server.
+
+1. When command line options is in use, this feature is enabled by default, the related option is `--enable-grpc-gateway`.
+
+```sh
+etcd --enable-grpc-gateway --data-dir=/path/to/data
+```
+
+Note this option is not shown in the output of `etcd --help`.
+
+2. When configuration file is used, this feature is disabled by default, please enable `enable-grpc-gateway` explicitly.
+
+```json
+# etcd.json
+{
+    "enable-grpc-gateway": true,
+    "data-dir": "/path/to/data"
+}
+```
+
+Indeed this distinction was eliminated by etcd in their master branch, but not backport to announced versions, so be care when deploy your etcd cluster.
diff --git a/FAQ_CN.md b/FAQ_CN.md
index 1842f9c..e9da543 100644
--- a/FAQ_CN.md
+++ b/FAQ_CN.md
@@ -261,3 +261,29 @@ APISIX 主要使用 [etcd.watchdir](https://github.com/api7/lua-resty-etcd/blob/
     apisix:
       id: "your-meaningful-id"
     ```
+
+## 为什么 `error.log` 中会有许多诸如 "failed to fetch data from etcd, failed to read etcd dir, etcd key: xxxxxx" 的错误？
+
+首先请确保 APISIX 和 etcd 之间不存在网络分区的情况。
+
+如果网络的确是健康的，请检查你的 etcd 集群是否启用了 [gRPC gateway](https://etcd.io/docs/v3.4.0/dev-guide/api_grpc_gateway/) 特性。然而，当你使用命令行参数或配置文件启动 etcd 时，此特性的默认启用情况又是不同的。
+
+1. 当使用命令行参数启动 etcd，该特性默认被启用，相关选项是 `enable-grpc-gateway`。
+
+```sh
+etcd --enable-grpc-gateway --data-dir=/path/to/data
+```
+
+注意该选项并没有展示在 `etcd --help` 的输出中。
+
+2. 使用配置文件时，该特性默认被关闭，请明确启用 `enable-grpc-gateway` 配置项。
+
+```json
+# etcd.json
+{
+    "enable-grpc-gateway": true,
+    "data-dir": "/path/to/data"
+}
+```
+
+事实上这种差别已经在 etcd 的 master 分支中消除，但并没有向后移植到已经发布的版本中，所以在部署 etcd 集群时，依然需要小心。