本文档采用自动化机器翻译技术翻译。尽管我们力求提供准确的译文，但不对翻译内容的完整性、准确性或可靠性作出任何保证。若出现任何内容不一致情况，请以原始英文版本为准，且原始英文版本为权威文本。

k3s etcd 快照

本页面描述了如何使用 k3s etcd-snapshot CLI 工具管理 etcd 快照以及如何从 etcd 快照恢复。

K3s etcd 快照存储在节点文件系统上，并可以选择上传到兼容 S3 的对象存储，以应对灾难恢复场景。快照可以按计划自动生成，也可以根据需要手动生成。k3s etcd-snapshot CLI 工具提供了一组子命令，可用于创建、删除和管理快照。

子命令说明

子命令	说明
`delete`	删除指定的快照
`ls`、`list`、`l`	列出快照
`prune`	去除超过配置保留数量的快照
`save`	触发按需 etcd 快照

delete

删除指定的快照

ls、list、l

列出快照

prune

去除超过配置保留数量的快照

save

触发按需 etcd 快照

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

创建快照

已安排
按需

计划快照默认启用，在系统时间的 00:00 和 12:00 生成，保留 5 个快照。计划快照的名称以 etcd-snapshot 开头，后跟节点名称和时间戳。

以下选项控制计划快照的操作：

标志说明

标志	说明
`--etcd-disable-snapshots`	禁用计划快照。
`--etcd-snapshot-name`	设置 etcd 计划快照的基本名称。（默认值：`etcd-snapshot`）
`--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 * * *`）。

--etcd-disable-snapshots

禁用计划快照。

--etcd-snapshot-name

设置 etcd 计划快照的基本名称。（默认值：etcd-snapshot）

--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 * * *）。

数据目录值默认为 /var/lib/rancher/k3s，可以通过设置 --data-dir 标志独立更改。

计划快照保存到服务器的 --etcd-snapshot-dir 值设置的路径。如果您希望它们在 S3 兼容的对象存储中复制，请参考 S3 配置选项。

可以通过运行 k3s etcd-snapshot save 命令手动保存快照。这些按需快照没有保留，用户需要通过使用 k3s etcd-snapshot delete 或 k3s etcd-snapshot prune 命令手动去除它们。按需快照的名称以 on-demand 开头，后跟节点名称和时间戳。

以下选项控制按需快照的操作：

标志说明

标志	说明
`--name`	设置 etcd 按需快照的基本名称。（默认值：`on-demand`）
`--etcd-snapshot-compress`	压缩 etcd 快照。
`--etcd-snapshot-dir`	保存数据库快照的目录。(默认位置：`$<data-dir>/db/snapshots`)

--name

设置 etcd 按需快照的基本名称。（默认值：on-demand）

--etcd-snapshot-compress

压缩 etcd 快照。

--etcd-snapshot-dir

保存数据库快照的目录。(默认位置：$<data-dir>/db/snapshots)

数据目录值默认为 /var/lib/rancher/k3s，可以通过设置 --data-dir 标志独立更改。

--name 标志只能在运行 k3s etcd-snapshot save 命令时设置。另外两个也可以是 k3s server 配置文件的一部分。

按需快照保存到服务器的 --etcd-snapshot-dir 值设置的路径。如果您希望它们在 S3 兼容的对象存储中复制，请参考 S3 配置选项。

删除快照

当快照数量超过配置的保留计数（默认5）时，计划快照会自动删除。最旧的快照会被优先去除。

要手动删除计划快照或按需快照，可以使用 k3s etcd-snapshot delete 命令：

k3s etcd-snapshot delete <SNAPSHOT-NAME-1> <SNAPSHOT-NAME-2> ...

prune 子命令会去除与名称前缀（默认 on-demand）匹配且超过配置保留计数的快照。它包括标志 --snapshot-retention 来设置保留计数。对于计划快照，它会覆盖默认的保留策略。按需快照没有保留策略，因此此标志是必需的。

将 "按需" 快照修剪到更少的数量：

k3s etcd-snapshot prune --snapshot-retention  <NUM-OF-SNAPSHOTS-TO-RETAIN>

将 "计划" 快照修剪到更少的数量：

k3s etcd-snapshot prune --name etcd-snapshot --etcd-snapshot-retention <NUM-OF-SNAPSHOTS-TO-RETAIN>

S3 兼容对象存储支持

K3s 支持将 etcd 快照复制到 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`	禁用 S3 通过 HTTPS
`--etcd-s3-timeout`	S3 超时（默认：`5m0s`）
`--etcd-s3-config-secret`	在 kube-system 命名空间中用于配置 S3 的秘密名称，如果启用了 etcd-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

禁用 S3 通过 HTTPS

--etcd-s3-timeout

S3 超时（默认：5m0s）

--etcd-s3-config-secret

在 kube-system 命名空间中用于配置 S3 的秘密名称，如果启用了 etcd-s3 且未设置其他 etcd-s3 选项。

例如，这就是如何在 S3 中创建和去除按需 etcd 快照的工作方式：

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret save
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created
on-demand-server-0-1753178523     s3://test-bucket/test-folder/on-demand-server-0-1753178523                        5062688 2025-07-22T10:02:03Z
on-demand-server-0-1753178523     file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-server-0-1753178523     5062688 2025-07-22T10:02:03Z

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret delete on-demand-server-0-1753178523
INFO[0000] Snapshot on-demand-server-0-1753178523 deleted.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created

S3 保留

版本门控

从版本 v1.34.0+k3s1、v1.33.4+k3s1、v1.32.8+k3s1、v1.31.12+k3s1 开始，K3s 包含一个新的 S3 保留标志。它的默认值与本地快照保留相同。

标志说明

标志	说明
`--etcd-s3-retention`	在 S3 中保留的快照数量。（默认值：`5`）

--etcd-s3-retention

在 S3 中保留的快照数量。（默认值：5）

S3 配置秘密支持

版本门控

自 2024 年 8 月发布以来，S3 配置秘密支持可用：v1.30.4+k3s1、v1.29.8+k3s1、v1.28.13+k3s1。

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

在恢复快照时，无法使用 S3 配置 Secret，因为在恢复期间 apiserver 不可用以提供 Secret。在恢复存储在 S3 上的快照时，必须通过 CLI 传递 S3 配置。

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

Secret 中的键对应于上述 --etcd-s3-* CLI 标志。 etcd-s3-endpoint-ca 键接受 PEM 编码的 CA 包，或者可以使用 etcd-s3-endpoint-ca-name 键指定 kube-system 命名空间中包含一个或多个 PEM 编码 CA 包的 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 在恢复快照时经过几个步骤：

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

在恢复快照时，您不需要使用创建快照的相同 K3s 版本；更高的次要版本也是可以接受的。

快照恢复步骤

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

单服务器
多台服务器

停止 K3s 服务：
```
systemctl stop k3s
```
运行 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 恢复快照并重置集群成员资格，然后打印一条消息，指示它已准备好重启：
Managed etcd cluster membership has been reset, restart without --cluster-reset flag now.
再次启动 K3s：
```
systemctl start k3s
```

如果在 K3s 配置文件中定义了 etcd-s3 备份配置，K3s 恢复将尝试从配置的 S3 存储桶中提取快照文件。在这种情况下，只有快照文件名应作为参数 --cluster-reset-restore-path 传递。要从本地快照文件恢复（当存在 etcd-s3 备份配置时），请添加参数 --etcd-s3=false，并在参数 --cluster-reset-restore-path 中传递本地快照文件的完整路径。

作为安全机制，当 K3s 重置集群时，它会在 /var/lib/rancher/k3s/server/db/reset-flag 创建一个空文件，以防止用户意外连续运行多个集群重置。当 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 恢复快照并重置集群成员资格，然后打印一条消息，指示它已准备好重新启动： Managed etcd cluster membership has been reset, restart without --cluster-reset flag now. Backup and delete ${datadir}/server/db on each peer etcd server and rejoin the nodes.
在 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
```

恢复到新主机

可以将 etcd 快照恢复到与创建该快照时所在主机不同的主机上。这样做时，必须传递在创建快照时原本使用的服务器词元，因为它用于解密快照中的启动数据。该过程与上述相同，但将步骤 2 更改为：

在创建快照的节点中保存以下值：/var/lib/rancher/k3s/server/token。这就是步骤 3 中的 <BACKED-UP-TOKEN-VALUE>。
将快照复制到新节点。节点中的路径在第 3 步中为 <PATH-TO-SNAPSHOT>。
使用以下命令在第一个服务器节点上启动从快照恢复：
```
k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
  --token=<BACKED-UP-TOKEN-VALUE>
```
词元值也可以在 K3s 配置文件中设置。

节点资源也包含在 etcd 快照中。如果要恢复到一组新节点，您需要手动删除集群中不再存在的旧节点。
如果在 K3s 配置文件中设置了词元，请确保它与 <BACKED-UP-TOKEN-VALUE> 相同，否则 K3s 将无法启动。

ETCD快照文件自定义资源

版本门槛

ETCD快照文件从 2023 年 11 月的版本开始可用：v1.28.4+k3s2，v1.27.8+k3s2，v1.26.11+k3s2，v1.25.16+k3s4。

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

$ 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

$ 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