etcd 备份与恢复#

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

安装 Alauda Container Platform Cluster Enhancer 插件后，会自动为集群配置创建一个 EtcdBackupConfiguration 资源。EtcdBackupConfiguration 包含备份数据源（control 节点、备份路径）、备份数据存储位置、备份方法等信息。基于该策略执行的每次备份都会生成一条新的备份记录，使你能够按需或按周期自动备份集群配置。

#前提条件

要启用 etcd 备份：

1. 从 <Term name="company" /> customer portal 下载 Alauda Container Platform Cluster Enhancer。
2. 上传软件包 到平台。
3. 在你的集群上安装插件。

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

#工作原理

• etcd 备份由 Alauda Container Platform Cluster Enhancer 提供
• 同时支持本地存储和 S3 兼容对象存储。本地备份会写入每个 control plane 节点上的一个目录中，默认路径为 /cpaas/backup。建议将该目录规划在一块专用磁盘上，并预留扩展空间；随着备份不断累积，将备份保存在根文件系统中可能会导致磁盘压力。配置 S3 存储后，会在 S3 bucket 中额外创建一份副本；本地备份仍会继续生成。
• 对于运行在 Immutable OS 上的集群，S3 存储是必需的（不支持本地存储）

#配置参考

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

#计划和保留

• schedule：使用标准 cron 语法定义备份频率。
  • 示例：0 0 * * *（每天午夜运行备份）。
• localStorage：配置本地备份存储。
  • path：每个 control plane 节点上存储备份的目录。默认值为 /cpaas/backup。请将其设置为由专用、可扩展磁盘支持的目录；请参见下面的存储说明。
  • ttl：备份文件的保留时长，单位为秒。超过该时长的备份将被自动删除。
    • 示例：7776000（约 90 天）。
• paused：设置为 true 可临时暂停自动备份，而不会删除配置。

示例配置：

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: /mnt/etcd-backup    # A directory on a dedicated, mounted backup disk
    ttl: "7776000"            # Retain for 90 days
  # ... other fields

#查看备份记录

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

#使用平台 UI

1. 在左侧导航栏中，单击 Operation Center > Monitor > Dashboards。
2. 单击页面右上角的 Switch。
3. 单击 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 存储，请按照以下步骤操作：

#前提条件

• 集群上已安装 Alauda Container Platform 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 中是否存在备份文件。

#etcd 恢复

警告：

• 此操作会对 etcd 集群执行灾难恢复，并覆盖现有数据。继续操作前，请确保你拥有有效的备份快照。
• 此操作具有较大风险。如果你不确定如何执行，请联系技术支持。
• 在恢复过程中，Kubernetes API Server 将不可用。

#前提条件

• Kubernetes 集群使用主机名部署（kubectl get node 显示主机名作为节点名称）。
• 存在可用的 etcd 备份快照。
• 集群因 etcd 节点故障而发生异常（例如，超过一半的 control plane 节点宕机）。
• 此恢复操作专为3 节点 control plane 集群设计。如果你的集群有 5 个或更多 control plane 节点，请联系技术支持获取帮助。

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

在所有 control plane 节点上执行以下命令：

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

# Stop kubelet
systemctl stop kubelet

# Backup etcdctl binary
cp $(find /var/lib/containerd/ -name etcdctl | tail -1) /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 备份快照复制到第一个 control plane 节点的 /tmp 目录，并命名为 snapshot.db。

#第 3 步：恢复 etcd

在第一个 control plane 节点上执行以下脚本以恢复快照。

注意： 以下脚本假定集群为 3 节点 control plane 集群。如果你的集群有 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 步：分发恢复后的数据

1. 将恢复后的数据目录传输到相应的 control plane 节点。使用 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/

2. 将数据恢复到每个 control plane 节点上的 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 步：重启集群组件

在所有 control plane 节点上执行以下命令：

# 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 步：验证恢复

1. 检查 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

2. 检查 Kubernetes pod 是否正常运行：

   kubectl get po -n kube-system

3. 在所有节点（包括 control plane 节点和 worker 节点）上重启 kubelet，以确保所有组件重新连接到已恢复的 etcd：

   systemctl restart kubelet

#配置管理

如需修改默认的 etcd 备份配置，请联系技术支持获取详细的配置选项和高级设置。