文档版本 v3.7-DRAFT 处于草稿状态。如需获取最新的稳定版文档，请参阅 v3.6。

将 etcd 从 3.3 升级到 3.4

关于将 etcd 从 3.3 升级到 3.4 的流程、检查清单和注意事项

在一般情况下，从 etcd 3.3 升级到 3.4 可以实现零停机、滚动升级：

逐个停止 etcd v3.3 进程，并将其替换为 etcd v3.4 进程
在所有 v3.4 进程运行后，v3.4 中的新功能即可在集群中使用

在开始升级之前，请通读本指南其余部分以做好准备。

升级检查清单

注意： 当从 v2 迁移且没有 v3 数据时，如果 etcd 从现有快照恢复但不存在 v3 的 ETCD_DATA_DIR/member/snap/db 文件，etcd 服务器 v3.2+ 将会 panic。这种情况发生在服务器已从 v2 迁移但之前没有 v3 数据时。这也防止了意外的 v3 数据丢失（例如 db 文件可能已被移动）。etcd 要求只有在存在 v3 数据的情况下才能进行后续的 v3 版本迁移。在 v3.0 服务器包含 v3 数据之前，请勿升级到更新的 v3 版本。

3.4 版本中的重点破坏性变更。

将 `ETCDCTL_API=3 etcdctl` 设为默认值

ETCDCTL_API=3 现在是默认值。

etcdctl set foo bar
Error: unknown command "set" for "etcdctl"

-etcdctl set foo bar
+ETCDCTL_API=2 etcdctl set foo bar
bar

ETCDCTL_API=3 etcdctl put foo bar
OK

-ETCDCTL_API=3 etcdctl put foo bar
+etcdctl put foo bar

将 `etcd --enable-v2=false` 设为默认值

现在默认启用 etcd --enable-v2=false。

这意味着，除非明确指定 etcd --enable-v2=true，否则 etcd v3.4 服务器将不再响应 v2 API 请求。

如果使用了 v2 API，请确保在 v3.4 中启用 v2 API：

-etcd
+etcd --enable-v2=true

其他 HTTP API 仍可正常工作（例如 [CLIENT-URL]/metrics、[CLIENT-URL]/health、v3 gRPC 网关）。

弃用 `etcd --ca-file` 和 `etcd --peer-ca-file` 参数

--ca-file 和 --peer-ca-file 参数已被弃用；自 v2.1 起已不推荐使用。

注意：设置此参数会自动启用客户端证书认证，无论 --client-cert-auth 设置为何值。

-etcd --ca-file ca-client.crt
+etcd --trusted-ca-file ca-client.crt

-etcd --peer-ca-file ca-peer.crt
+etcd --peer-trusted-ca-file ca-peer.crt

弃用 `grpc.ErrClientConnClosing` 错误

grpc.ErrClientConnClosing 已在 gRPC >= 1.10 中被弃用。

import (
+	"go.etcd.io/etcd/clientv3"

	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
)

_, err := kvc.Get(ctx, "a")
-if err == grpc.ErrClientConnClosing {
+if clientv3.IsConnCanceled(err) {

// or
+s, ok := status.FromError(err)
+if ok {
+  if s.Code() == codes.Canceled

客户端拨号需使用 `grpc.WithBlock`

新的客户端负载均衡器使用异步解析器将端点传递给 gRPC 拨号函数。因此，v3.4 客户端需要 grpc.WithBlock 拨号选项，以等待底层连接建立完成。

import (
	"time"
	"go.etcd.io/etcd/clientv3"
+	"google.golang.org/grpc"
)

+// "grpc.WithBlock()" to block until the underlying connection is up
ccfg := clientv3.Config{
  Endpoints:            []string{"localhost:2379"},
  DialTimeout:          time.Second,
+ DialOptions:          []grpc.DialOption{grpc.WithBlock()},
  DialKeepAliveTime:    time.Second,
  DialKeepAliveTimeout: 500 * time.Millisecond,
}

弃用 `etcd_debugging_mvcc_db_total_size_in_bytes` Prometheus 指标

v3.4 将 etcd_debugging_mvcc_db_total_size_in_bytes Prometheus 指标升级为 etcd_mvcc_db_total_size_in_bytes，以鼓励对 etcd 存储进行监控。

etcd_debugging_mvcc_db_total_size_in_bytes 在 v3.4 中仍保留以支持向后兼容，将在 v3.5 中完全移除。

-etcd_debugging_mvcc_db_total_size_in_bytes
+etcd_mvcc_db_total_size_in_bytes