17370845950

备份前须确认 etcd 启用 v3 API，验证 endpoint health；用 go-etcd/v3 的 SnapshotSave 可控备份；恢复时需匹配版本、清空 data-dir、设置正确启动参数；快照不含运行时状态和缓存。

备份前必须确认 etcd 是否启用了 v3 API

Kubernetes 1.6+ 默认使用 etcd v3，而 etcdctl 的 v2 和 v3 命令不兼容。若误用 v2 模式备份，etcdctl backup 会静默失败或生成空快照。执行前务必验证：

ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint health

返回 healthy 才代表 v3 接口可用。否则需检查 ETCDCTL_API 环境变量是否被覆盖、证书路径是否拼写错误（如把 server.crt 写成 peer.crt）。

用 go-etcd/v3 客户端直接调用 SnapshotSave 实现可控备份

纯 shell 调用 etcdctl snapshot save 难以嵌入 Go 应用逻辑中。改用官方 go.etcd.io/etcd/client/v3 的 SnapshotSave 方法更可靠，支持超时控制与错误分类：

• ctx 必须带 timeout，避免因网络抖动卡死（建议 5 * time.Minute）
• 目标文件需提前创建并设置 0600 权限，防止备份中途被其他进程截断
• 不要复用已有 client 连接做备份——SnapshotSave 是独立 HTTP 请求，与 KV 操作隔离

cli, _ := clientv3.New(clientv3.Config{
  Endpoints:   []string{"https://127.0.0.1:2379"},
  DialTimeout: 5 * time.Second,
  TLS: &tls.Config{
    Certificates: []tls.Certificate{cert},
    RootCAs:      caPool,
  },
})
f, _ := os.Create("/backup/etcd-snapshot-$(date +%s).db")
defer f.Close()
if err := cli.SnapshotSave(context.WithTimeout(context.Background(), 5*time.Minute), f); err != nil {
  log.Fatal("snapshot save failed:", err) // 注意：err 可能是 io.EOF 或 tls handshake timeout
}

恢复时 etcd 启动参数必须匹配原集群版本与数据目录权限

从快照恢复不是简单替换文件。常见失败点：

• --initial-cluster 和 --initial-advertise-peer-urls 必须与原集群完全一致，否则启动后无法加入集群
• --data-dir 目录必须为空，且属主为运行 etcd 的用户（如 etcd:etcd），否则报 permission denied on lock file
• 若原集群使用 etcd v3.5.x 备份，不能用 v3.4.x 的 etcdctl snapshot restore 恢复，会提示 unsupported version

正确流程是先停掉所有 etcd 成员，清空 --data-dir，再执行：

ETCDCTL_API=3 etcdctl --write-out=table snapshot restore /backup/etcd-snapshot-1712345678.db \
  --data-dir=/var/lib/etcd-restored \
  --name=etcd-node-1 \
  --initial-cluster="etcd-node-1=https://10.0.0.1:2380,etcd-node-2=https://10.0.0.2:2380" \
  --initial-cluster-token=etcd-cluster-1 \
  --initial-advertise-peer-urls=https://10.0.0.1:2380

备份内容不含 kube-apiserver 状态缓存和节点本地资源

etcd 快照只保存 Kubernetes 的声明式状态（Pod、Service、Secret 等对象），但以下内容不会被还原：

• 节点上的 containerd 或 docker 运行时状态（如正在运行的容器、临时卷挂载）
• kube-apiserver 的 watch 缓存、openapi schema 缓存
• Node 对象的 Status.Addresses 可能过期，需等 kubelet 重连后自动更新
• 外部存储（如 S3 中的 VolumeSnapshotContent）需单独备份，etcd 不存其二进制数据

这意味着恢复后需等待所有节点重新上报状态，并手动验证 DaemonSet 是否在全部节点上重建成功——这步容易被忽略，但直接影响业务可用性。