将 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 的新特性

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

升级检查列表

警告

从没有 v3 数据的 v2 迁移时，如果 etcd 从现有快照恢复，但不存在 v3 ETCD_DATA_DIR/member/snap/db 文件，etcd v3.2+ 服务器会发生崩溃。这种情况出现在服务器由 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