k3s etcd-snapshot

本页介绍了使用k3s etcd-snapshot CLI 管理 etcd 快照的方法，以及为k3s server 进程配置 etcd 定期快照，以及使用k3s server --cluster-reset 命令重置 etcd 集群成员资格并可选地恢复 etcd 快照。

创建快照

快照保存到服务器的--etcd-snapshot-dir 值设置的路径，默认值为${data-dir}/server/db/snapshots。data-dir 值默认为/var/lib/rancher/k3s，可以通过设置--data-dir 标志独立更改。

定期快照

定期快照默认情况下处于启用状态，系统时间为 00:00 和 12:00，保留 5 个快照。要配置快照间隔或保留的快照数量，请参阅快照配置选项。

定期快照的名称以etcd-snapshot 开头，后跟节点名称和时间戳。基本名称可以通过服务器配置中的--etcd-snapshot-name 标志更改。

按需快照

可以通过运行k3s etcd-snapshot save 命令手动保存快照。

按需快照的名称以on-demand 开头，后跟节点名称和时间戳。基本名称可以在保存快照时使用--name 标志更改。

快照配置选项

这些标志可以传递给k3s server 命令以重置 etcd 集群，并可选地从快照恢复。

标志	描述
`--cluster-reset`	忘记所有对等节点并成为新集群的唯一成员。这也可以使用环境变量`[$K3S_CLUSTER_RESET]` 设置
`--cluster-reset-restore-path`	要恢复的快照文件路径

这些标志对k3s server 和k3s etcd-snapshot 都有效，但是当传递给k3s etcd-snapshot 时，可以省略--etcd- 前缀以避免冗余。标志可以在命令行中传递，也可以在配置文件中传递，这可能更易于使用。

标志	描述
`--etcd-disable-snapshots`	禁用定期快照
`--etcd-snapshot-compress`	压缩 etcd 快照
`--etcd-snapshot-dir`	保存数据库快照的目录。（默认位置：`${data-dir}/db/snapshots`）
`--etcd-snapshot-retention`	要保留的快照数量（默认：5）
`--etcd-snapshot-schedule-cron`	快照间隔时间，以 cron 规范表示。例如，每 5 小时`0 /5 * `（默认：`0 /12 * * *`）

S3 兼容对象存储支持

K3s 支持将 etcd 快照写入 S3 兼容的对象存储，并从 S3 兼容的对象存储恢复 etcd 快照。S3 支持适用于按需快照和定期快照。

标志	描述
`--etcd-s3`	启用备份到 S3
`--etcd-s3-endpoint`	S3 终结点 URL
`--etcd-s3-endpoint-ca`	连接到 S3 终结点的 S3 自定义 CA 证书
`--etcd-s3-skip-ssl-verify`	禁用 S3 SSL 证书验证
`--etcd-s3-access-key`	S3 访问密钥
`--etcd-s3-secret-key`	S3 密钥
`--etcd-s3-bucket`	S3 存储桶名称
`--etcd-s3-region`	S3 区域/存储桶位置（可选）。默认为 us-east-1
`--etcd-s3-folder`	S3 文件夹
`--etcd-s3-proxy`	连接到 S3 时使用的代理服务器，覆盖任何与代理相关的环境变量
`--etcd-s3-insecure`	禁用通过 HTTPS 使用 S3
`--etcd-s3-timeout`	S3 超时时间（默认：`5m0s`）
`--etcd-s3-config-secret`	用于配置 S3 的 kube-system 命名空间中的密钥名称，如果启用了 etcd-s3 且未设置其他 etcd-s3 选项

要执行按需 etcd 快照并将其保存到 S3

k3s etcd-snapshot save \
  --s3 \
  --s3-bucket=<S3-BUCKET-NAME> \
  --s3-access-key=<S3-ACCESS-KEY> \
  --s3-secret-key=<S3-SECRET-KEY>

要从 S3 执行按需 etcd 快照恢复，首先确保 K3s 未运行。然后运行以下命令

k3s server \
  --cluster-init \
  --cluster-reset \
  --etcd-s3 \
  --cluster-reset-restore-path=<SNAPSHOT-NAME> \
  --etcd-s3-bucket=<S3-BUCKET-NAME> \
  --etcd-s3-access-key=<S3-ACCESS-KEY> \
  --etcd-s3-secret-key=<S3-SECRET-KEY>

S3 配置密钥支持

版本门

S3 配置密钥支持适用于 2024 年 8 月版本：v1.30.4+k3s1、v1.29.8+k3s1、v1.28.13+k3s1

K3s 支持从 Kubernetes 密钥中读取 etcd S3 快照配置。出于安全原因，或者如果需要在不重启 K3s 的情况下轮换凭据，这可能优于在 K3s CLI 标志或配置文件中硬编码凭据。要通过密钥传递 S3 快照配置，请使用--etcd-s3 和--etcd-s3-config-secret=<SECRET-NAME> 启动 K3s。在启动 K3s 时，密钥无需存在，但每次执行快照保存/列出/删除/修剪操作时，都会检查该密钥。

在恢复 S3 上存储的快照时，不能使用 S3 配置密钥，因为 apiserver 在恢复过程中不可用以提供该密钥。恢复存储在 S3 上的快照时，必须通过 CLI 传递 S3 配置。

注意

仅传递--etcd-s3 和--etcd-s3-config-secret 标志以启用密钥。
如果设置了任何其他 S3 配置标志，则会忽略该密钥。

密钥中的键对应于上面列出的--etcd-s3-* CLI 标志。etcd-s3-endpoint-ca 键接受 PEM 编码的 CA 捆绑包，或者可以使用etcd-s3-endpoint-ca-name 键指定包含一个或多个 PEM 编码的 CA 捆绑包的kube-system 命名空间中的 ConfigMap 名称。

apiVersion: v1
kind: Secret
metadata:
  name: k3s-etcd-snapshot-s3-config
  namespace: kube-system
type: etcd.k3s.cattle.io/s3-config-secret
stringData:
  etcd-s3-endpoint: ""
  etcd-s3-endpoint-ca: ""
  etcd-s3-endpoint-ca-name: ""
  etcd-s3-skip-ssl-verify: "false"
  etcd-s3-access-key: "AWS_ACCESS_KEY_ID"
  etcd-s3-secret-key: "AWS_SECRET_ACCESS_KEY"
  etcd-s3-bucket: "bucket"
  etcd-s3-folder: "folder"
  etcd-s3-region: "us-east-1"
  etcd-s3-insecure: "false"
  etcd-s3-timeout: "5m"
  etcd-s3-proxy: ""

管理快照

k3s 支持一组用于处理 etcd 快照的子命令。

子命令	描述
delete	删除给定的快照。
ls, list, l	列出快照。
prune	删除超过配置保留数量的快照。
save	立即触发 etcd 快照。

无论 etcd 快照存储在本地还是在 S3 兼容的对象存储中，这些命令都将按预期执行。

有关 etcd 快照子命令的更多信息，请运行k3s etcd-snapshot --help。

从 S3 删除快照。

k3s etcd-snapshot delete          \
  --s3                            \
  --s3-bucket=<S3-BUCKET-NAME>    \
  --s3-access-key=<S3-ACCESS-KEY> \
  --s3-secret-key=<S3-SECRET-KEY> \
  <SNAPSHOT-NAME>

使用默认保留策略（5）修剪本地快照。prune 子命令接受一个额外的标志--snapshot-retention，它允许覆盖默认保留策略。

k3s etcd-snapshot prune

k3s etcd-snapshot prune --snapshot-retention 10

ETCDSnapshotFile 自定义资源

版本门

ETCDSnapshotFiles 可用于 2023 年 11 月版本：v1.28.4+k3s2、v1.27.8+k3s2、v1.26.11+k3s2、v1.25.16+k3s4

可以使用任何 Kubernetes 客户端通过列出或描述集群范围的ETCDSnapshotFile 资源来远程查看快照。与仅显示该节点可见的快照的k3s etcd-snapshot list 命令不同，ETCDSnapshotFile 资源跟踪集群成员中存在的所有快照。

root@k3s-server-1:~# kubectl get etcdsnapshotfile
NAME                                             SNAPSHOTNAME                        NODE           LOCATION                                                                            SIZE      CREATIONTIME
local-on-demand-k3s-server-1-1730308816-3e9290   on-demand-k3s-server-1-1730308816   k3s-server-1   file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-k3s-server-1-1730308816   2891808   2024-10-30T17:20:16Z
s3-on-demand-k3s-server-1-1730308816-79b15c      on-demand-k3s-server-1-1730308816   s3             s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816                                2891808   2024-10-30T17:20:16Z

root@k3s-server-1:~# kubectl describe etcdsnapshotfile s3-on-demand-k3s-server-1-1730308816-79b15c
Name:         s3-on-demand-k3s-server-1-1730308816-79b15c
Namespace:
Labels:       etcd.k3s.cattle.io/snapshot-storage-node=s3
Annotations:  etcd.k3s.cattle.io/snapshot-token-hash: b4b83cda3099
API Version:  k3s.cattle.io/v1
Kind:         ETCDSnapshotFile
Metadata:
  Creation Timestamp:  2024-10-30T17:20:16Z
  Finalizers:
    wrangler.cattle.io/managed-etcd-snapshots-controller
  Generation:        1
  Resource Version:  790
  UID:               bec9a51c-dbbe-4746-922e-a5136bef53fc
Spec:
  Location:   s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816
  Node Name:  s3
  s3:
    Bucket:           etcd
    Endpoint:         s3.example.com
    Prefix:           k3s-test
    Region:           us-east-1
    Skip SSL Verify:  true
  Snapshot Name:      on-demand-k3s-server-1-1730308816
Status:
  Creation Time:  2024-10-30T17:20:16Z
  Ready To Use:   true
  Size:           2891808
Events:
  Type    Reason               Age   From            Message
  ----    ------               ----  ----            -------
  Normal  ETCDSnapshotCreated  113s  k3s-supervisor  Snapshot on-demand-k3s-server-1-1730308816 saved on S3

恢复快照

K3s 在恢复快照时会执行以下步骤

如果快照存储在 S3 上，则将文件下载到快照目录。
如果快照已压缩，则将其解压缩。
如果存在，则将当前 etcd 数据库文件移动到${data-dir}/server/db/etcd-old-$TIMESTAMP/。
将快照的内容提取到磁盘，并验证校验和。
启动 etcd，并从集群中删除除当前节点以外的所有 etcd 集群成员。
从数据存储中提取 CA 证书和其他机密数据，并将其写入磁盘，以便日后使用。
恢复完成，并且可以正常重启 K3s 并使用执行恢复操作的服务器。
（可选）代理和控制平面服务器可以正常启动。
（可选）etcd 服务器可以重新启动，以在删除旧数据库文件后重新加入集群。

快照恢复步骤

选择与您的集群配置匹配的选项卡。

单个服务器
多个服务器

停止 K3s 服务
```
systemctl stop k3s
```
使用--cluster-reset 标志运行k3s server，并使用--cluster-reset-restore-path 指示要恢复的快照路径。如果快照存储在 S3 上，请提供 S3 配置标志（--etcd-s3、--etcd-s3-bucket 等），并将快照的文件名作为恢复路径。

注意
使用--cluster-reset 标志而不指定要恢复的快照只会将 etcd 集群重置为单个成员，而不会恢复快照。
```
k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
```
结果：K3s 恢复快照并重置集群成员身份，然后打印一条消息，表明它已准备好重新启动。
托管 etcd 集群成员身份已重置，现在无需 --cluster-reset 标志即可重新启动。
再次启动 K3s。
```
systemctl start k3s
```

在此示例中，有 3 台服务器：S1、S2 和 S3。快照位于 S1 上。

停止所有服务器上的 K3s。
```
systemctl stop k3s
```
在 S1 上，运行 k3s server 并使用 --cluster-reset 选项，以及 --cluster-reset-restore-path 指示要恢复的快照路径。如果快照存储在 S3 上，请提供 S3 配置标志（--etcd-s3、--etcd-s3-bucket 等），并将快照的仅文件名作为还原路径。

注意
使用--cluster-reset 标志而不指定要恢复的快照只会将 etcd 集群重置为单个成员，而不会恢复快照。
```
k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
```
结果：K3s 恢复快照并重置集群成员身份，然后打印一条消息，表明它已准备好重新启动。
托管 etcd 集群成员身份已重置，现在无需 --cluster-reset 标志即可重新启动。
备份并删除每个对等 etcd 服务器上的 ${datadir}/server/db，然后重新加入节点。
在 S1 上，再次启动 K3s。
```
systemctl start k3s
```
在 S2 和 S3 上，删除数据目录 /var/lib/rancher/k3s/server/db/。
```
rm -rf /var/lib/rancher/k3s/server/db/
```
在 S2 和 S3 上，再次启动 K3s 以加入已恢复的集群。
```
systemctl start k3s
```

创建快照​

定期快照​

按需快照​

快照配置选项​

S3 兼容对象存储支持​

S3 配置密钥支持​

管理快照​

ETCDSnapshotFile 自定义资源​

恢复快照​

快照恢复步骤​