etcd 备份与恢复

集群上的 etcd 服务是一个分布式键值存储，用于保存集群配置信息。etcd 部署在集群的所有控制平面节点上。

安装 Cluster Enhancer 插件后，会为集群配置自动创建一个 EtcdBackupConfiguration 资源。EtcdBackupConfiguration 包含备份数据源、控制平面节点路径、备份数据存储位置和备份方法。基于策略执行的每次备份都会生成一条新的备份记录，从而支持按需和定时的集群配置备份。

前提条件

要启用 etcd 备份：

从 Customer Portal 下载 Cluster Enhancer。
上传包到平台。
在集群上安装插件。

安装完成后，会自动创建一个 EtcdBackupConfiguration 资源。

工作原理

etcd 备份由 Cluster Enhancer 提供。
支持本地存储和 S3 兼容的对象存储。本地备份会写入每个控制平面节点上的一个目录，默认是 /var/cpaas/backup。请为该目录规划足够的容量，以容纳 etcd 数据大小和保留周期。配置 S3 存储会在 S3 bucket 中创建一份额外副本；本地备份仍会继续生成。
对于 Immutable OS 集群，本地备份默认使用 /var/cpaas/backup。仍可通过 remoteStorage.s3 使用 S3 存储。

配置参考

你可以配置 EtcdBackupConfiguration 资源，以自定义备份计划、保留策略和存储选项。

计划与保留

schedule：使用标准 cron 语法定义备份频率。
- 示例：0 0 * * *（每天午夜运行备份）。
localStorage：配置本地备份存储。
- path：每个控制平面节点上存储备份的目录。默认值为 /var/cpaas/backup。请将其设置为一个能够容纳 etcd 数据大小和已配置保留周期的目录；请参见下方的存储说明。
- ttl：备份文件的保留期，单位为秒。超过此时长的备份将被自动删除。
  - 示例：7776000（约 90 天）。
paused：设置为 true 可临时暂停自动备份，而不删除配置。

WARNING

在启用 etcd 备份之前，请先规划本地备份的存储容量。本地备份会累积在控制平面节点上，并会一直保留到其 ttl 过期，因此 /var/cpaas/backup 必须为预期的备份大小和保留周期预留足够的可用空间。

配置示例：

apiVersion: enhancement.cluster.alauda.io/v1
kind: EtcdBackupConfiguration
metadata:
  name: etcd-backup-default
spec:
  schedule: "0 0 * * *"       # Run daily at 00:00
  paused: false               # Enable backups
  localStorage:
    path: /var/cpaas/backup   # Local backup directory on each control plane node
    ttl: "7776000"            # Retain for 90 days
  # ... other fields

查看备份记录

要查看 etcd 备份记录，可以使用平台 UI 或命令行。

使用平台 UI

在左侧导航栏中，单击 Operation Center > Monitor > Dashboards。
单击页面右上角的 Switch。
单击 Cluster → etcd backup 查看 etcd 备份记录。

使用 CLI

你可以通过检查 EtcdBackupConfiguration 资源的 status 字段来验证备份状态和历史记录：

kubectl get etcdbackupconfiguration etcd-backup-default -o yaml

输出包含一个 status.records 列表，其中包含每次备份的详细信息，包括：

backupTimestamp：创建备份的时间。
fileName：备份文件名称（例如，snapshot-etcd-<date>-<time>-<ip>.tar）。
result：备份操作的结果（例如，Success）。

S3 备份配置

要为 etcd 备份启用 S3 存储，请按以下步骤操作：

前提条件

已在集群上安装 Cluster Enhancer。

步骤 1：创建 S3 Secret

准备你的 S3 访问凭据，并在 cpaas-system 命名空间中创建一个 Kubernetes secret：

export ACCESS_KEY="your-access-key"
export SECRET_KEY="your-secret-key"

kubectl create secret generic etcd-backup-s3-secret \
  --from-literal=ACCESS_KEY="$ACCESS_KEY" \
  --from-literal=SECRET_KEY="$SECRET_KEY" \
  --dry-run=client -n cpaas-system -o yaml | kubectl apply -f -

步骤 2：配置 EtcdBackupConfiguration

修改 EtcdBackupConfiguration 资源，添加带有 S3 配置的 remoteStorage 字段：

spec:
  remoteStorage:
    s3:
      endpoint: "your-s3-endpoint"  # e.g.: https://s3.bucket.com
      region: "your-s3-region"
      bucket: "your-s3-bucket"
      dir: "your-s3-bucket-dir"
      skipTLSVerify: false  # Set to true only for self-signed certificates
      secretRef: etcd-backup-s3-secret

步骤 3：验证备份

触发一次手动 etcd 备份以验证配置：

# Set environment variables
token="your-platform-token"
platform_url="your-platform-url"
cluster_name="your-cluster-name"

# Trigger backup
curl $platform_url/kubernetes/$cluster_name/apis/enhancement.cluster.alauda.io/v1/etcdbackupconfigurations/etcd-backup-default/exec \
  -k -H "Authorization: Bearer $token"

备份完成后，请确认你的 S3 bucket 中存在备份文件。

在进行恢复准备时，请使用备份记录中显示的 fileName 和已配置的 remoteStorage.s3.dir 值，从 S3 下载 tar 归档：

aws --endpoint-url <s3-endpoint> s3 cp \
  s3://<bucket>/<dir>/<backup-file-name> \
  /tmp/snapshot-etcd.tar

mkdir -p /tmp/etcd-restore
tar -xf /tmp/snapshot-etcd.tar -C /tmp/etcd-restore
find /tmp/etcd-restore -name 'snapshot-etcd-*.db' -type f

etcd 恢复

警告：

此操作会对 etcd 集群执行破坏性恢复，并覆盖现有数据。继续之前，请确保你有有效的备份快照。

该操作步骤风险较高。如果你不确定如何操作，请联系技术支持。

在恢复过程中，Kubernetes API Server 将不可用。

前提条件

Kubernetes 集群使用主机名部署（kubectl get node 显示主机名作为节点名称）。
已有一个 etcd 备份快照可用。
集群因 etcd 节点故障而出现异常（例如，超过一半的控制平面节点宕机）。
此恢复操作步骤专为 3 节点控制平面 集群设计。如果你的集群有 5 个或更多控制平面节点，请联系技术支持以获取帮助。
在 Immutable OS 上，请在开始恢复前确认每个控制平面节点上都存在 /var/lib/etcd、/etc/kubernetes/manifests/etcd.yaml 和 /etc/kubernetes/pki/etcd/。
在 Immutable OS 上，etcdctl 可能不在宿主机的 PATH 中。请在 /var/lib/containerd 下查找，或使用包含兼容 etcdctl 二进制文件的容器镜像。

步骤 1：备份原始数据并修改 etcd 配置

在所有控制平面节点上执行以下命令：

# Create backup directory
mkdir -p /root/backup_$(date +%Y%m%d%H)/old-etcd/

# Stop kubelet
systemctl stop kubelet

# Prepare etcdctl binary
ETCDCTL_PATH="$(find /var/lib/containerd/ -name etcdctl -type f | tail -1)"
if [ -z "$ETCDCTL_PATH" ]; then
  echo "etcdctl was not found under /var/lib/containerd. Use a container image that includes a compatible etcdctl binary."
  exit 1
fi
cp "$ETCDCTL_PATH" /root/etcdctl
chmod +x /root/etcdctl

# Remove etcd containers
crictl ps -a | grep etcd | awk '{print $1}' | xargs -r crictl rm -f

# Backup etcd data and kubernetes configuration
cp -a /var/lib/etcd/* /root/backup_$(date +%Y%m%d%H)/old-etcd/
rm -rf /var/lib/etcd/*
cp -r /etc/kubernetes/ /root/backup_$(date +%Y%m%d%H)/old-etcd/

# Modify etcd.yaml to use existing cluster state
sed -i /initial-cluster-state=/d /etc/kubernetes/manifests/etcd.yaml
sed -i '/initial-cluster=/a\    - --initial-cluster-state=existing' /etc/kubernetes/manifests/etcd.yaml

注意：请验证 /etc/kubernetes/manifests/etcd.yaml 中 --initial-cluster-state=existing 的缩进。

步骤 2：复制备份快照

将选定的 etcd 备份快照复制到第一个控制平面节点上的 /tmp 目录，并将其命名为 snapshot.db。

如果备份 tar 归档文件已保存在本地，则从 /var/cpaas/backup 中提取它：

mkdir -p /tmp/etcd-restore
tar -xf "$(ls -1t /var/cpaas/backup/snapshot-etcd-*.tar | head -1)" -C /tmp/etcd-restore
cp "$(find /tmp/etcd-restore -name 'snapshot-etcd-*.db' -type f | head -1)" /tmp/snapshot.db

如果备份 tar 归档文件存储在 S3 中，请先下载它，然后再提取快照文件：

aws --endpoint-url <s3-endpoint> s3 cp \
  s3://<bucket>/<dir>/<backup-file-name> \
  /tmp/snapshot-etcd.tar

mkdir -p /tmp/etcd-restore
tar -xf /tmp/snapshot-etcd.tar -C /tmp/etcd-restore
cp "$(find /tmp/etcd-restore -name 'snapshot-etcd-*.db' -type f | head -1)" /tmp/snapshot.db

步骤 3：恢复 etcd

在第一个控制平面节点上执行以下脚本以恢复快照。

注意： 以下脚本假定集群为 3 节点控制平面。如果你的集群有 5 个或更多节点，请联系技术支持。

#!/usr/bin/env bash

# Set etcd node IPs (Replace with actual IPs)
export ETCD_1=1.1.1.1
export ETCD_2=2.2.2.2
export ETCD_3=3.3.3.3

# Set corresponding node hostnames (Replace with actual hostnames)
export ETCD_1_HOSTNAME=etcd-1
export ETCD_2_HOSTNAME=etcd-2
export ETCD_3_HOSTNAME=etcd-3

export ETCDCTL_API=3

# Loop for 3 nodes. Adjust '1 2 3' if you have a different number of nodes.
for n in 1 2 3; do
  ip_var=ETCD_${n}
  host_var=ETCD_${n}_HOSTNAME

  ip=${!ip_var}
  host=${!host_var}

  echo "Restoring for node: ${host} (${ip})..."

  rm -rf /tmp/etcd
  /root/etcdctl snapshot restore /tmp/snapshot.db \
    --cert=/etc/kubernetes/pki/etcd/server.crt \
    --key=/etc/kubernetes/pki/etcd/server.key \
    --cacert=/etc/kubernetes/pki/etcd/ca.crt \
    --skip-hash-check=true \
    --data-dir=/tmp/etcd \
    --name "${host}" \
    --initial-cluster \
      ${ETCD_1_HOSTNAME}=https://${ETCD_1}:2380,\
${ETCD_2_HOSTNAME}=https://${ETCD_2}:2380,\
${ETCD_3_HOSTNAME}=https://${ETCD_3}:2380 \
    --initial-advertise-peer-urls https://"${ip}":2380 && \
    mv /tmp/etcd /root/etcd_"${host}"

  echo "Restoration for ${host} completed. Data directory: /root/etcd_${host}"
done

脚本完成后，会在 /root 目录中生成三个目录（etcd_$host）。

步骤 4：分发恢复后的数据

将恢复后的数据目录传输到相应的控制平面节点。使用 scp 或类似工具，将步骤 3 中生成的目录（/root/etcd_<hostname>）从第一个节点复制到其他节点。

例如，传输到 etcd-2 和 etcd-3：
# Replace <etcd-2-ip> and <etcd-3-ip> with actual IPs scp -r /root/etcd_etcd-2 root@<etcd-2-ip>:/root/ scp -r /root/etcd_etcd-3 root@<etcd-3-ip>:/root/

将数据恢复到每个控制平面节点上的 etcd 数据目录（/var/lib/etcd）。

# On etcd-1:
cp -r /root/etcd_etcd-1/member/* /var/lib/etcd/

# On etcd-2:
cp -r /root/etcd_etcd-2/member/* /var/lib/etcd/

# On etcd-3:
cp -r /root/etcd_etcd-3/member/* /var/lib/etcd/

步骤 5：重启集群组件

在所有控制平面节点上执行以下命令：

# Remove Kubernetes control plane containers
crictl ps -a | grep -E "kube-api|kube-sche|kube-contro" | awk '{print $1}' | xargs -r crictl rm -f

# Restart kubelet
systemctl restart kubelet

步骤 6：验证恢复

检查 etcd 集群是否健康。你可以在任意一个 etcd Pod 内执行此命令，或使用宿主机上的 etcdctl 二进制文件：

# Using etcdctl on the host
export ETCDCTL_API=3
/root/etcdctl --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  --endpoints=https://127.0.0.1:2379 \
  endpoint health

检查 Kubernetes Pod 是否正常运行：
kubectl get po -n kube-system
在所有节点（包括控制平面节点和 worker 节点）上重启 kubelet，以确保所有组件重新连接到已恢复的 etcd：
systemctl restart kubelet

#etcd 备份与恢复

#目录

#前提条件

#工作原理

#配置参考

#计划与保留

#查看备份记录

#使用平台 UI

#使用 CLI

#S3 备份配置

#前提条件

#步骤 1：创建 S3 Secret

#步骤 2：配置 EtcdBackupConfiguration

#步骤 3：验证备份

#etcd 恢复

#前提条件

#步骤 1：备份原始数据并修改 etcd 配置

#步骤 2：复制备份快照

#步骤 3：恢复 etcd

#步骤 4：分发恢复后的数据

#步骤 5：重启集群组件

#步骤 6：验证恢复

#配置管理

etcd 备份与恢复

目录

前提条件

工作原理

配置参考

计划与保留

查看备份记录

使用平台 UI

使用 CLI

S3 备份配置

前提条件

步骤 1：创建 S3 Secret

步骤 2：配置 EtcdBackupConfiguration

步骤 3：验证备份

etcd 恢复

前提条件

步骤 1：备份原始数据并修改 etcd 配置

步骤 2：复制备份快照

步骤 3：恢复 etcd

步骤 4：分发恢复后的数据

步骤 5：重启集群组件

步骤 6：验证恢复

配置管理