RKE2 Cluster Restore Fails When Using Full Path with etcd-s3 Backup Configuration

• RKE2 clusters with etcd-s3 backup configuration enabled.
• Affected RKE2 versions: v1.25.14+rke2r1 to v1.32.1+rke2r1 (and likely future versions).
• S3-compatible object storage (e.g., DigitalOcean Spaces, AWS S3).

When attempting to restore an RKE2 cluster using the rke2 server --cluster-reset --cluster-reset-restore-path=<PATH-TO-SNAPSHOT> command, and an etcd-s3 backup configuration is defined in /etc/rancher/rke2/config.yaml, the restore operation fails with the error: FATA[0020] starting kubernetes: preparing server: start managed database: failed to download snapshot from S3: The specified key does not exist. This occurs even when the specified snapshot file exists locally.

INFO[0020] Checking if S3 bucket aseymour-backup exists
INFO[0020] S3 bucket example-backup exists
INFO[0020] Adding S3 client to cache
FATA[0020] starting kubernetes: preparing server: start managed database: failed to download snapshot from S3: The specified key does not exist.

To avoid this issue when restoring from an S3 backup, and an etcd-s3 backup configuration is present, use the snapshot filename only in the --cluster-reset-restore-path argument. For example:

rke2 server \
  --cluster-reset \
  --cluster-reset-restore-path=<SNAPSHOT-NAME>

To restore from a local snapshot file when an etcd-s3 backup configuration is defined, use the --etcd-s3=false flag and provide the full path to the snapshot file in the --cluster-reset-restore-path argument. For example: 

rke2 server \
  --cluster-reset \
  --cluster-reset-restore-path=<FULL-PATH-TO-SNAPSHOT> \ 
  --etcd-s3=false

When an etcd-s3 backup configuration is present, RKE2 interprets the --cluster-reset-restore-path argument differently. If a full path is provided, RKE2 incorrectly attempts to locate a file with that path within the configured S3 bucket, leading to a key not found error. Providing only the filename instructs RKE2 to retrieve the snapshot from the configured S3 bucket.

This behaviour can be observed across multiple RKE2 versions, and it is the intended design behaviour when using etcd-s3 backups.
The documented restore command, can be found here: https://docs.rke2.io/datastore/backup_restore#other-notes-on-restoring-a-snapshot