在Kubernetes中用etcdctl执行快照备份时遇‘save命令未知’错误

1. 确保ETCDCTL_API环境变量正确生效 #

你遇到的unknown command "save"错误，核心原因是ETCDCTL_API环境变量未正确设置为3，导致etcdctl默认使用v2版本语法（v2中备份命令为backup而非snapshot save）。

• 先在etcd容器内执行echo $ETCDCTL_API，确认输出为3。若未输出，先执行export ETCDCTL_API=3再执行备份命令；或者直接将变量与命令绑定，确保生效：

  ETCDCTL_API=3 etcdctl snapshot save <backup-file-location> --endpoints=https://127.0.0.1:2379 --cacert=<trusted-ca-file> --cert=<cert-file> --key=<key-file>
  

• 若API版本已设为3仍报错，检查etcdctl版本：执行ETCDCTL_API=3 etcdctl version，若版本低于3.2，部分命令格式不兼容，需升级etcdctl或调整命令。

2. 确认证书文件路径的准确性 #

Kubernetes集群中etcd的证书默认存放在容器内的/etc/kubernetes/pki/etcd/目录，需确保替换的占位符对应实际文件：

• --cacert=/etc/kubernetes/pki/etcd/ca.crt
• --cert=/etc/kubernetes/pki/etcd/server.crt
• --key=/etc/kubernetes/pki/etcd/server.key
  提前验证文件存在性：

ls -l /etc/kubernetes/pki/etcd/

3. 选择正确的执行节点 #

多master集群中，仅需在**任意一个运行正常的etcd节点（即master节点上的etcd Pod）**执行备份即可，无需操作所有节点：

• 先通过kubectl get pods -n kube-system筛选Running状态的etcd Pod，再进入容器：

  kubectl exec -it <etcd-pod-name> -n kube-system -- sh
  

4. 保证备份文件可持久化 #

若将备份文件存放在容器内部，容器销毁后文件会丢失，建议：

• 备份到临时目录后，复制到宿主机：

  # 容器内执行备份
  ETCDCTL_API=3 etcdctl snapshot save /tmp/etcd-snapshot.db --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
  # 复制到宿主机
  kubectl cp kube-system/<etcd-pod-name>:/tmp/etcd-snapshot.db /宿主机存储路径/etcd-snapshot.db
  

• 提前验证备份目录的写入权限：touch /tmp/test-file，无报错则说明可写。

5. 验证备份有效性 #

备份完成后必须验证快照可用性，避免备份失效：

ETCDCTL_API=3 etcdctl snapshot status /tmp/etcd-snapshot.db

若输出快照的版本、哈希值等信息，说明备份成功。

内容的提问来源于stack exchange，提问作者pwoltschk