mirrors/velero
1
0
Fork 0
mirror of https://github.com/vmware-tanzu/velero.git synced 2026-09-21 07:24:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: Add documentation about --write-sparse-files flag for disk space issues during restore (#9221)

Browse Source 
- Added cross-references in troubleshooting.md and file-system-backup.md to the Write Sparse files documentation
- Documented how to use --write-sparse-files flag when restores fail due to disk space constraints
- Clarified important limitation: only works if PV had sparse files during backup that would free up space
- Removed enhanced error messages and code changes (documentation-only approach per feedback)

This addresses issue #2812 by providing clear guidance to users when restores fail due to disk space constraints.

Signed-off-by: Tiger Kaovilai <tkaovila@redhat.com>
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Tiger Kaovilai
2026-09-17 15:31:29 +08:00
committed by GitHub
co-authored by Claude
parent 7d88457591
commit fa01151214
3 changed files with 25 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
changelogs/unreleased/9221-kaovilai
+1
View File
@@ -0,0 +1 @@
docs: Add documentation about --write-sparse-files flag for disk space issues during restore
site/content/docs/main/file-system-backup.md
+6
View File
@@ -602,6 +602,12 @@ To understand which backup method was used for your volumes:
**Note:** A volume appearing in the "skipped PVs" summary doesn't mean it wasn't backed up - it may have been backed up via volume snapshot instead.
### Disk space issues during restore
If restores fail due to "no space left on device" errors, the `--write-sparse-files` option may help in specific scenarios. However, this only works if the persistent volume had sparse files during backup that would free up enough space for the restore process. If the volume doesn't contain sparse files, this option will not resolve the disk space issue.
For more information, see [Write Sparse files](restore-reference.md#write-sparse-files) in the restore documentation.
## Backup Method Decision Flow
When Velero encounters a volume during backup, it follows this decision flow:
site/content/docs/main/troubleshooting.md
+18
View File
@@ -250,6 +250,24 @@ To resolve it, please use Kopia maintenance CLI to set the ownership correctly,
Please refer to [Issue 9007](https://github.com/velero-io/velero/issues/9007) for more information.
## Disk space issues during restore
If you encounter "no space left on device" errors during restore, the `--write-sparse-files` flag may help in certain scenarios.
Example error message:
```
Velero: pod volume restore failed: error restoring volume: error creating .velero directory for done file: mkdir /host_pods/60880bf2-9d1c-47cf-ba8f-5f8db43b385b/volumes/kubernetes.io~csi/pvc-ee79e0f0-ed62-44f7-987e-16efca1d1cd5/mount/.velero: no space left on device
```
**Important Limitation**: The `--write-sparse-files` flag only works if the persistent volume had sparse files during backup that would free up enough space for the done file. If the volume doesn't contain sparse files, this option will not resolve the disk space issue.
To try using sparse files during restore:
```bash
velero restore create <RESTORE_NAME> --from-backup <BACKUP_NAME> --write-sparse-files
```
See [Write Sparse files](restore-reference.md#write-sparse-files) for more details on using this option.
[1]: debugging-restores.md
[2]: debugging-install.md
[3]: file-system-backup.md