A Rancher-provisioned or standalone, RKE2 or K3s cluster
Rancher 配置或独立的 RKE2 或 K3s 集群

In the rke2-server or k3s service logs, errors with "deadline exceeded" are seen when attempting to reconcile and interact with the S3 endpoint for snapshots.
在 rke2-server 或 k3s 服务日志中，尝试与 S3 端点进行对账和交互快照时，会出现“deadline outededed”的错误。

<span style="background-color:#efefef"><code>Jan 27 15:01:46 xxxx rke2[3120757]: time="2026-01-27T15:01:46+08:00" level=warning msg="Failed to get object metadata: Head \"<a data-cke-saved-href="https://xxx.yy.org/rancher-downstream/prod-cluster/.metadata/etcd-snapshot-xxxx.yy.org-1753833604.zip/" href="https://xxx.yy.org/rancher-downstream/prod-cluster/.metadata/etcd-snapshot-xxxx.yy.org-1753833604.zip/">https://xxx.yy.org/rancher-downstream/prod-cluster/.metadata/etcd-snapshot-xxxx.yy.org-1753833604.zip\</a>": context deadline exceeded"
Jan 27 15:01:46 xxxx rke2[3120757]: time="2026-01-27T15:01:46+08:00" level=warning msg="Failed to get object metadata: context deadline exceeded"
Jan 27 15:01:46 xxxx rke2[3120757]: time="2026-01-27T15:01:46+08:00" level=error msg="Error retrieving S3 snapshots for reconciliation: context deadline exceeded"</code></span>

If the network latency is high or the number of objects in the bucket introduces delays, the S3 snapshot handling fails to complete. For a cluster provisioned by Rancher, the dashboard may not show all of the available snapshots in S3.
如果网络延迟较高或桶中对象数量增加导致延迟，S3 快照处理将失败。对于由 Rancher 配置的集群，仪表盘可能不会显示 S3 中所有可用的快照。

To workaround the latency, the S3 operation timeout can be increased to allow the RKE2/K3s supervisor process enough time to complete the API calls. At the time of writing, this timeout is not configurable within Rancher, for Rancher-provisioned RKE2 and K3s clusters, so the configuration is also added directly on the etcd nodes in those clusters.
为了绕过延迟，可以延长 S3 作超时，以便 RKE2/K3s 的主管程序有足够时间完成 API 调用。撰写本文时，Rancher 内部无法配置该超时，适用于 Rancher 配置的 RKE2 和 K3s 集群，因此配置也会直接添加到这些集群的 etcd 节点上。

The default timeout is 5 minutes, in the below steps a 10 minute timeout has been used.
默认超时为5分钟，以下步骤中使用了10分钟超时。

Configuration  配置

Apply the configuration to the RKE2/K3s config file on every etcd node in the cluster.
把配置应用到集群中每个 etcd 节点的 RKE2/K3s 配置文件上。

1. Configure the etcd-s3-timeout parameter in the the RKE2 or K3s configuration file (/etc/rancher/rke2/config.yaml or /etc/rancher/k3s/config.yaml) per the following example:
   在 RKE2 或 K3s 配置文件（/etc/rancher/rke2/config.yaml 或 /etc/rancher/k3s/config.yaml）中配置 etcd-s3-timeout 参数 ，具体示例如下：

   <span style="background-color:#efefef"><code>etcd-s3-timeout: 10m0s</code></span>

2. After updating the configuration file, you will need to restart the RKE2/K3s service to apply the changes:
   更新配置文件后，您需要重启 RKE2/K3s 服务以应用以下更改：
   • On RKE2 etcd nodes: systemctl restart rke2-server
     在 RKE2 etcd 节点上：systemctl restart rke2-server
   • On K3s etcd nodes: systemctl restart k3
     在 K3s 的 etcd 节点上：systemctl restart k3

Verification  验证

Once the timeout is increased and the rke2-server/k3s services have been restarted, you can verify the configuration.
一旦超时增加，rke2-server/k3s 服务重启，你就可以验证配置。

• For standalone clusters, run the manual list command, to verify that the list matches the snapshots within S3.
  对于独立集群，运行手动列表命令，以验证列表是否与 S3 中的快照匹配。
  • For RKE2 clusters: rke2 etcd-snapshost list 
    对于 RKE2 集群：rke2 etcd-snapshost 列表  
  • For K3s clusters: k3s etcd-snapshot list
    对于 K3s 集群：k3s etcd 快照列表
• For Rancher-provisioned clusters, check the Rancher UI. Navigate to Cluster Management, select the applicable cluster, and click the Snapshots tab. The snapshots should represent the current state of snapshot files in S3, once Rancher successfully synchronizes the list from the RKE2/K3s cluster.
  对于 Rancher 配置的集群，请查看 Rancher 界面。进入集群管理 ，选择相应的集群，然后点击快照标签。快照应表示 S3 中快照文件的当前状态，前提是 Rancher 成功同步 RKE2/K3s 集群的列表。

The issue is caused by a network timeout when retrieving S3 snapshots. Increasing the etcd-s3-timeout parameter in the RKE2/K3s configuration resolves the problem.
问题是由获取 S3 快照时网络超时引起的。在 RKE2/K3s 配置中提高 etcd-s3 超时参数即可解决此问题。

If the "failed to read metadata" is seen in the errors, this relates to RKE2/K3s storing a small .zip or .json metadata file alongside each snapshot.
如果错误中出现“ 未读取元数据 ”，这与 RKE2/K3s 在每个快照旁存储一个小型 .zip 或 .json 元数据文件有关。

• The Timeout: When RKE2/K3s scans the bucket, it tries to read the metadata for each snapshot file. If the S3 provider (or the network path) doesn't respond fast enough, the whole process exits, leaving you with an empty or outdated list.
  暂停时间： 当 RKE2/K3s 扫描桶时，它会尝试读取每个快照文件的元数据。如果 S3 提供商（或网络路径）响应不够快，整个流程就会退出，留下一个空的或过时的列表。

• The Cause: This may need additional assistance to understand, for example - the S3 endpoint may intermittently respond slowly or timeout, network congestion or underlying hardware configuration may introduce packet loss. Investigation is needed to resolve persistent performance issues.
  原因： 例如，这可能需要额外的帮助来理解——S3 端点可能间歇性响应缓慢或超时，网络拥堵或底层硬件配置可能导致丢包。需要调查以解决持续的性能问题。